@eagleoutice/flowr 2.4.8 → 2.6.0

package/linter/rules/deprecated-functions.js

@@ -2,50 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEPRECATED_FUNCTIONS = void 0;
 const linter_format_1 = require("../linter-format");
-const flowr_search_builder_1 = require("../../search/flowr-search-builder");
-const dfg_1 = require("../../util/mermaid/dfg");
-const search_enrichers_1 = require("../../search/search-executor/search-enrichers");
-const flowr_search_filters_1 = require("../../search/flowr-search-filters");
 const linter_tags_1 = require("../linter-tags");
+const function_finder_util_1 = require("./function-finder-util");
 exports.DEPRECATED_FUNCTIONS = {
-    createSearch: (config) => flowr_search_builder_1.Q.all()
-        .with(search_enrichers_1.Enrichment.CallTargets, { onlyBuiltin: true })
-        .filter({
-        name: flowr_search_filters_1.FlowrFilter.MatchesEnrichment,
-        args: {
-            enrichment: search_enrichers_1.Enrichment.CallTargets,
-            test: (0, flowr_search_filters_1.testFunctionsIgnoringPackage)(config.deprecatedFunctions)
-        }
-    }),
-    processSearchResult: (elements) => {
-        const metadata = {
-            totalDeprecatedCalls: 0,
-            totalDeprecatedFunctionDefinitions: 0
-        };
-        return {
-            results: elements.getElements()
-                .flatMap(element => {
-                metadata.totalDeprecatedCalls++;
-                return (0, search_enrichers_1.enrichmentContent)(element, search_enrichers_1.Enrichment.CallTargets).targets.map(target => {
-                    metadata.totalDeprecatedFunctionDefinitions++;
-                    return {
-                        range: element.node.info.fullRange,
-                        target: target
-                    };
-                });
-            })
-                .map(element => ({
-                certainty: linter_format_1.LintingResultCertainty.Certain,
-                function: element.target,
-                range: element.range
-            })),
-            '.meta': metadata
-        };
-    },
-    prettyPrint: {
-        [linter_format_1.LintingPrettyPrintContext.Query]: result => `Function \`${result.function}\` at ${(0, dfg_1.formatRange)(result.range)}`,
-        [linter_format_1.LintingPrettyPrintContext.Full]: result => `Function \`${result.function}\` called at ${(0, dfg_1.formatRange)(result.range)} is deprecated`
-    },
+    createSearch: (config) => function_finder_util_1.functionFinderUtil.createSearch(config.fns),
+    processSearchResult: function_finder_util_1.functionFinderUtil.processSearchResult,
+    prettyPrint: function_finder_util_1.functionFinderUtil.prettyPrint('deprecated'),
     info: {
         name: 'Deprecated Functions',
         tags: [linter_tags_1.LintingRuleTag.Deprecated, linter_tags_1.LintingRuleTag.Smell, linter_tags_1.LintingRuleTag.Usability, linter_tags_1.LintingRuleTag.Reproducibility],
@@ -53,7 +15,7 @@ exports.DEPRECATED_FUNCTIONS = {
         certainty: linter_format_1.LintingRuleCertainty.BestEffort,
         description: 'Marks deprecated functions that should not be used anymore.',
         defaultConfig: {
-            deprecatedFunctions: ['all_equal', 'arrange_all', 'distinct_all', 'filter_all', 'group_by_all', 'summarise_all', 'mutate_all', 'select_all', 'vars', 'all_vars', 'id', 'failwith', 'select_vars', 'rename_vars', 'select_var', 'current_vars', 'bench_tbls', 'compare_tbls', 'compare_tbls2', 'eval_tbls', 'eval_tbls2', 'location', 'changes', 'combine', 'do', 'funs', 'add_count_', 'add_tally_', 'arrange_', 'count_', 'distinct_', 'do_', 'filter_', 'funs_', 'group_by_', 'group_indices_', 'mutate_', 'tally_', 'transmute_', 'rename_', 'rename_vars_', 'select_', 'select_vars_', 'slice_', 'summarise_', 'summarize_', 'summarise_each', 'src_local', 'tbl_df', 'add_rownames', 'group_nest', 'group_split', 'with_groups', 'nest_by', 'progress_estimated', 'recode', 'sample_n', 'top_n', 'transmute', 'fct_explicit_na', 'aes_', 'aes_auto', 'annotation_logticks', 'is.Coord', 'coord_flip', 'coord_map', 'is.facet', 'fortify', 'is.ggproto', 'guide_train', 'is.ggplot', 'qplot', 'is.theme', 'gg_dep', 'liply', 'isplit2', 'list_along', 'cross', 'invoke', 'at_depth', 'prepend', 'rerun', 'splice', '`%@%`', 'rbernoulli', 'rdunif', 'when', 'update_list', 'map_raw', 'accumulate', 'reduce_right', 'flatten', 'map_dfr', 'as_vector', 'transpose', 'melt_delim', 'melt_fwf', 'melt_table', 'read_table2', 'str_interp', 'as_tibble', 'data_frame', 'tibble_', 'data_frame_', 'lst_', 'as_data_frame', 'as.tibble', 'frame_data', 'trunc_mat', 'is.tibble', 'tidy_names', 'set_tidy_names', 'repair_names', 'extract_numeric', 'complete_', 'drop_na_', 'expand_', 'crossing_', 'nesting_', 'extract_', 'fill_', 'gather_', 'nest_', 'separate_rows_', 'separate_', 'spread_', 'unite_', 'unnest_', 'extract', 'gather', 'nest_legacy', 'separate_rows', 'separate', 'spread',]
+            fns: ['all_equal', 'arrange_all', 'distinct_all', 'filter_all', 'group_by_all', 'summarise_all', 'mutate_all', 'select_all', 'vars', 'all_vars', 'id', 'failwith', 'select_vars', 'rename_vars', 'select_var', 'current_vars', 'bench_tbls', 'compare_tbls', 'compare_tbls2', 'eval_tbls', 'eval_tbls2', 'location', 'changes', 'combine', 'do', 'funs', 'add_count_', 'add_tally_', 'arrange_', 'count_', 'distinct_', 'do_', 'filter_', 'funs_', 'group_by_', 'group_indices_', 'mutate_', 'tally_', 'transmute_', 'rename_', 'rename_vars_', 'select_', 'select_vars_', 'slice_', 'summarise_', 'summarize_', 'summarise_each', 'src_local', 'tbl_df', 'add_rownames', 'group_nest', 'group_split', 'with_groups', 'nest_by', 'progress_estimated', 'recode', 'sample_n', 'top_n', 'transmute', 'fct_explicit_na', 'aes_', 'aes_auto', 'annotation_logticks', 'is.Coord', 'coord_flip', 'coord_map', 'is.facet', 'fortify', 'is.ggproto', 'guide_train', 'is.ggplot', 'qplot', 'is.theme', 'gg_dep', 'liply', 'isplit2', 'list_along', 'cross', 'invoke', 'at_depth', 'prepend', 'rerun', 'splice', '`%@%`', 'rbernoulli', 'rdunif', 'when', 'update_list', 'map_raw', 'accumulate', 'reduce_right', 'flatten', 'map_dfr', 'as_vector', 'transpose', 'melt_delim', 'melt_fwf', 'melt_table', 'read_table2', 'str_interp', 'as_tibble', 'data_frame', 'tibble_', 'data_frame_', 'lst_', 'as_data_frame', 'as.tibble', 'frame_data', 'trunc_mat', 'is.tibble', 'tidy_names', 'set_tidy_names', 'repair_names', 'extract_numeric', 'complete_', 'drop_na_', 'expand_', 'crossing_', 'nesting_', 'extract_', 'fill_', 'gather_', 'nest_', 'separate_rows_', 'separate_', 'spread_', 'unite_', 'unnest_', 'extract', 'gather', 'nest_legacy', 'separate_rows', 'separate', 'spread',]
         }
     }
 };

package/linter/rules/file-path-validity.d.ts

@@ -31,10 +31,11 @@ export interface FilePathValidityMetadata extends MergeableRecord {
     totalValid: number;
 }
 export declare const FILE_PATH_VALIDITY: {
-    readonly createSearch: (config: FilePathValidityConfig) => import("../../search/flowr-search-builder").FlowrSearchBuilder<"from-query", ["with"], import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../../search/flowr-search").FlowrSearchElements<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../../search/flowr-search").FlowrSearchElement<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>>;
+    readonly createSearch: (config: FilePathValidityConfig) => import("../../search/flowr-search-builder").FlowrSearchBuilder<"from-query", ["with"], import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, Promise<import("../../search/flowr-search").FlowrSearchElements<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../../search/flowr-search").FlowrSearchElement<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>>>;
     readonly processSearchResult: (elements: import("../../search/flowr-search").FlowrSearchElements<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../../search/flowr-search").FlowrSearchElement<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>, config: FilePathValidityConfig, data: {
         normalize: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
         dataflow: import("../../dataflow/info").DataflowInformation;
+        cfg: import("../../control-flow/control-flow-graph").ControlFlowInformation;
         config: import("../../config").FlowrConfigOptions;
     }) => {
         results: FilePathValidityResult[];

package/linter/rules/file-path-validity.js

@@ -26,9 +26,9 @@ exports.FILE_PATH_VALIDITY = {
             totalWritesBeforeAlways: 0,
             totalValid: 0
         };
+        const results = elements.enrichmentContent(search_enrichers_1.Enrichment.QueryData).queries['dependencies'];
         return {
             results: elements.getElements().flatMap(element => {
-                const results = elements.enrichmentContent(search_enrichers_1.Enrichment.QueryData).queries['dependencies'];
                 const matchingRead = results.read.find(r => r.nodeId == element.node.info.id);
                 if (!matchingRead) {
                     return [];

package/linter/rules/function-finder-util.d.ts

@@ -0,0 +1,51 @@
+import type { SourceRange } from '../../util/range';
+import type { Identifier } from '../../dataflow/environments/identifier';
+import type { LintingResult } from '../linter-format';
+import { LintingResultCertainty } from '../linter-format';
+import type { FlowrSearchElement, FlowrSearchElements } from '../../search/flowr-search';
+import type { NormalizedAst, ParentInformation } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
+import type { MergeableRecord } from '../../util/objects';
+import type { DataflowInformation } from '../../dataflow/info';
+import type { FlowrConfigOptions } from '../../config';
+import type { FunctionInfo } from '../../queries/catalog/dependencies-query/function-info/function-info';
+export interface FunctionsResult extends LintingResult {
+    function: string;
+    range: SourceRange;
+}
+export interface FunctionsMetadata extends MergeableRecord {
+    totalCalls: number;
+    totalFunctionDefinitions: number;
+}
+export interface FunctionsToDetectConfig extends MergeableRecord {
+    /**
+     * The list of function names that should be marked in the given context.
+     */
+    fns: readonly string[];
+}
+/**
+ * This helper object collects utility functions used to create linting rules that search for specific functions.
+ */
+export declare const functionFinderUtil: {
+    createSearch: (functions: readonly string[]) => import("../../search/flowr-search-builder").FlowrSearchBuilder<"all", ["with", "filter"], ParentInformation, Promise<FlowrSearchElements<ParentInformation, [] | FlowrSearchElement<ParentInformation>[]>>>;
+    processSearchResult: <T extends FlowrSearchElement<ParentInformation>[]>(elements: FlowrSearchElements<ParentInformation, T>, _config: FunctionsToDetectConfig, _data: {
+        normalize: NormalizedAst;
+        dataflow: DataflowInformation;
+        config: FlowrConfigOptions;
+    }, refineSearch?: (elements: T) => T) => {
+        results: {
+            certainty: LintingResultCertainty;
+            function: Identifier;
+            range: SourceRange;
+        }[];
+        '.meta': FunctionsMetadata;
+    };
+    prettyPrint: (functionType: string) => {
+        query: (result: FunctionsResult) => string;
+        full: (result: FunctionsResult) => string;
+    };
+    requireArgumentValue(element: FlowrSearchElement<ParentInformation>, pool: readonly FunctionInfo[], data: {
+        normalize: NormalizedAst;
+        dataflow: DataflowInformation;
+        config: FlowrConfigOptions;
+    }, requireValue: RegExp | string | undefined): boolean;
+};

package/linter/rules/function-finder-util.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.functionFinderUtil = void 0;
+const flowr_search_builder_1 = require("../../search/flowr-search-builder");
+const flowr_search_filters_1 = require("../../search/flowr-search-filters");
+const search_enrichers_1 = require("../../search/search-executor/search-enrichers");
+const linter_format_1 = require("../linter-format");
+const dfg_1 = require("../../util/mermaid/dfg");
+const assert_1 = require("../../util/assert");
+const resolve_argument_1 = require("../../dataflow/eval/resolve/resolve-argument");
+const vertex_1 = require("../../dataflow/graph/vertex");
+const dependencies_query_format_1 = require("../../queries/catalog/dependencies-query/dependencies-query-format");
+/**
+ * This helper object collects utility functions used to create linting rules that search for specific functions.
+ */
+exports.functionFinderUtil = {
+    createSearch: (functions) => {
+        return (flowr_search_builder_1.Q.all()
+            .with(search_enrichers_1.Enrichment.CallTargets, { onlyBuiltin: true })
+            .filter({
+            name: flowr_search_filters_1.FlowrFilter.MatchesEnrichment,
+            args: {
+                enrichment: search_enrichers_1.Enrichment.CallTargets,
+                test: (0, flowr_search_filters_1.testFunctionsIgnoringPackage)(functions)
+            }
+        }));
+    },
+    processSearchResult: (elements, _config, _data, refineSearch = e => e) => {
+        const metadata = {
+            totalCalls: 0,
+            totalFunctionDefinitions: 0
+        };
+        const results = refineSearch(elements.getElements())
+            .flatMap(element => {
+            metadata.totalCalls++;
+            return (0, search_enrichers_1.enrichmentContent)(element, search_enrichers_1.Enrichment.CallTargets).targets.map(target => {
+                metadata.totalFunctionDefinitions++;
+                return {
+                    node: element.node,
+                    range: element.node.info.fullRange,
+                    target: target
+                };
+            });
+        });
+        return {
+            results: results.map(element => ({
+                certainty: linter_format_1.LintingResultCertainty.Certain,
+                function: element.target,
+                range: element.range
+            })),
+            '.meta': metadata
+        };
+    },
+    prettyPrint: (functionType) => {
+        return {
+            [linter_format_1.LintingPrettyPrintContext.Query]: (result) => `Function \`${result.function}\` at ${(0, dfg_1.formatRange)(result.range)}`,
+            [linter_format_1.LintingPrettyPrintContext.Full]: (result) => `Function \`${result.function}\` called at ${(0, dfg_1.formatRange)(result.range)} is related to ${functionType}`
+        };
+    },
+    requireArgumentValue(element, pool, data, requireValue) {
+        const info = pool.find(f => f.name === element.node.lexeme);
+        /* if we have no additional info, we assume they always access the network */
+        if (info === undefined) {
+            return true;
+        }
+        const vert = data.dataflow.graph.getVertex(element.node.info.id);
+        if ((0, vertex_1.isFunctionCallVertex)(vert)) {
+            const args = (0, resolve_argument_1.getArgumentStringValue)(data.config.solver.variables, data.dataflow.graph, vert, info.argIdx, info.argName, info.resolveValue);
+            // we obtain all values, at least one of them has to trigger for the request
+            const argValues = args ? args.values().flatMap(v => [...v]).filter(assert_1.isNotUndefined).toArray() : [];
+            /* if there are no arguments we assume they may access the network, otherwise we check for the flag */
+            return argValues.length === 0 || argValues.some(v => v === dependencies_query_format_1.Unknown || (requireValue instanceof RegExp ? requireValue.test(v) : v === requireValue));
+        }
+        return false;
+    }
+};
+//# sourceMappingURL=function-finder-util.js.map

package/linter/rules/naming-convention.d.ts

@@ -41,10 +41,11 @@ export declare function getMostUsedCasing(symbols: {
 export declare function fixCasing(identifier: string, convention: CasingConvention): string | undefined;
 export declare function createNamingConventionQuickFixes(graph: DataflowGraph, nodeId: NodeId, replacement: string, conv: CasingConvention): LintQuickFixReplacement[] | undefined;
 export declare const NAMING_CONVENTION: {
-    readonly createSearch: (_config: NamingConventionConfig) => import("../../search/flowr-search-builder").FlowrSearchBuilder<"all", ["filter"], import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../../search/flowr-search").FlowrSearchElements<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, [] | import("../../search/flowr-search").FlowrSearchElement<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>>;
+    readonly createSearch: (_config: NamingConventionConfig) => import("../../search/flowr-search-builder").FlowrSearchBuilder<"all", ["filter"], import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, Promise<import("../../search/flowr-search").FlowrSearchElements<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, [] | import("../../search/flowr-search").FlowrSearchElement<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>>>;
     readonly processSearchResult: (elements: import("../../search/flowr-search").FlowrSearchElements<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../../search/flowr-search").FlowrSearchElement<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>, config: NamingConventionConfig, data: {
         normalize: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
         dataflow: import("../../dataflow/info").DataflowInformation;
+        cfg: import("../../control-flow/control-flow-graph").ControlFlowInformation;
         config: import("../../config").FlowrConfigOptions;
     }) => {
         results: {

package/linter/rules/network-functions.d.ts

@@ -0,0 +1,40 @@
+import { LintingRuleCertainty } from '../linter-format';
+import type { FunctionsMetadata, FunctionsResult } from './function-finder-util';
+import { LintingRuleTag } from '../linter-tags';
+import type { MergeableRecord } from '../../util/objects';
+export interface NetworkFunctionsConfig extends MergeableRecord {
+    /** The list of function names that should be marked in the given context if their arguments match. */
+    fns: readonly string[];
+    /** only trigger if the function's read argument is linked to a value that matches this pattern */
+    onlyTriggerWithArgument?: RegExp | string;
+}
+export declare const NETWORK_FUNCTIONS: {
+    readonly createSearch: (config: NetworkFunctionsConfig) => import("../../search/flowr-search-builder").FlowrSearchBuilder<"all", ["with", "filter"], import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, Promise<import("../../search/flowr-search").FlowrSearchElements<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, [] | import("../../search/flowr-search").FlowrSearchElement<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>>>;
+    readonly processSearchResult: (e: import("../../search/flowr-search").FlowrSearchElements<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../../search/flowr-search").FlowrSearchElement<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>, c: NetworkFunctionsConfig, d: {
+        normalize: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
+        dataflow: import("../../dataflow/info").DataflowInformation;
+        cfg: import("../../control-flow/control-flow-graph").ControlFlowInformation;
+        config: import("../../config").FlowrConfigOptions;
+    }) => {
+        results: {
+            certainty: import("../linter-format").LintingResultCertainty;
+            function: import("../../dataflow/environments/identifier").Identifier;
+            range: import("../../util/range").SourceRange;
+        }[];
+        '.meta': FunctionsMetadata;
+    };
+    readonly prettyPrint: {
+        query: (result: FunctionsResult) => string;
+        full: (result: FunctionsResult) => string;
+    };
+    readonly info: {
+        readonly name: "Network Functions";
+        readonly tags: readonly [LintingRuleTag.Reproducibility, LintingRuleTag.Security, LintingRuleTag.Performance, LintingRuleTag.Smell];
+        readonly certainty: LintingRuleCertainty.BestEffort;
+        readonly description: "Marks network functions that execute network operations, such as downloading files or making HTTP requests.";
+        readonly defaultConfig: {
+            readonly fns: readonly ["read.table", "read.csv", "read.csv2", "read.delim", "read.delim2", "readRDS", "download.file", "url", "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "content", "handle", "get_callback", "VERB", "fread", "gzcon", "readlines", "source", "load", "curl_download", "curl_fetch_memory", "getURL", "getForm", "read_html", "html_nodes", "html_text", "fromJSON", "read.xlsx", "drive_download", "drive_get", "s3read_using", "s3write_using", "storage_download", "AnnotationHub", "ExperimentHub"];
+            readonly onlyTriggerWithArgument: RegExp;
+        };
+    };
+};

package/linter/rules/network-functions.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NETWORK_FUNCTIONS = void 0;
+const linter_format_1 = require("../linter-format");
+const function_finder_util_1 = require("./function-finder-util");
+const linter_tags_1 = require("../linter-tags");
+const read_functions_1 = require("../../queries/catalog/dependencies-query/function-info/read-functions");
+exports.NETWORK_FUNCTIONS = {
+    createSearch: (config) => function_finder_util_1.functionFinderUtil.createSearch(config.fns),
+    processSearchResult: (e, c, d) => function_finder_util_1.functionFinderUtil.processSearchResult(e, c, d, es => es.filter(e => function_finder_util_1.functionFinderUtil.requireArgumentValue(e, read_functions_1.ReadFunctions, d, c.onlyTriggerWithArgument))),
+    prettyPrint: function_finder_util_1.functionFinderUtil.prettyPrint('network operations'),
+    info: {
+        name: 'Network Functions',
+        tags: [linter_tags_1.LintingRuleTag.Reproducibility, linter_tags_1.LintingRuleTag.Security, linter_tags_1.LintingRuleTag.Performance, linter_tags_1.LintingRuleTag.Smell],
+        // ensures all network functions found are actually network functions through its limited config, but doesn't find all network functions since the config is pre-crawled, and the DFG may be over-approximated
+        certainty: linter_format_1.LintingRuleCertainty.BestEffort,
+        description: 'Marks network functions that execute network operations, such as downloading files or making HTTP requests.',
+        defaultConfig: {
+            fns: ['read.table', 'read.csv', 'read.csv2', 'read.delim', 'read.delim2', 'readRDS', 'download.file', 'url', 'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'content', 'handle', 'get_callback', 'VERB', 'fread', 'gzcon', 'readlines', 'source', 'load', 'curl_download', 'curl_fetch_memory', 'getURL', 'getForm', 'read_html', 'html_nodes', 'html_text', 'fromJSON', 'read.xlsx', 'drive_download', 'drive_get', 's3read_using', 's3write_using', 'storage_download', 'AnnotationHub', 'ExperimentHub'],
+            onlyTriggerWithArgument: /^(https?|ftps?|file):\/\//
+        }
+    }
+};
+//# sourceMappingURL=network-functions.js.map

package/linter/rules/seeded-randomness.d.ts

@@ -30,10 +30,11 @@ export interface SeededRandomnessMeta extends MergeableRecord {
     callsWithNonConstantProducers: number;
 }
 export declare const SEEDED_RANDOMNESS: {
-    readonly createSearch: (config: SeededRandomnessConfig) => import("../../search/flowr-search-builder").FlowrSearchBuilder<"all", ["with", "filter", "with"], import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../../search/flowr-search").FlowrSearchElements<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../../search/flowr-search").FlowrSearchElement<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>>;
+    readonly createSearch: (config: SeededRandomnessConfig) => import("../../search/flowr-search-builder").FlowrSearchBuilder<"all", ["with", "filter", "with"], import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, Promise<import("../../search/flowr-search").FlowrSearchElements<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../../search/flowr-search").FlowrSearchElement<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>>>;
     readonly processSearchResult: (elements: import("../../search/flowr-search").FlowrSearchElements<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../../search/flowr-search").FlowrSearchElement<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>, config: SeededRandomnessConfig, { dataflow }: {
         normalize: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
         dataflow: import("../../dataflow/info").DataflowInformation;
+        cfg: import("../../control-flow/control-flow-graph").ControlFlowInformation;
         config: import("../../config").FlowrConfigOptions;
     }) => {
         results: {

package/linter/rules/unused-definition.d.ts

@@ -18,10 +18,11 @@ export interface UnusedDefinitionMetadata extends MergeableRecord {
     totalConsidered: number;
 }
 export declare const UNUSED_DEFINITION: {
-    readonly createSearch: (config: UnusedDefinitionConfig) => import("../../search/flowr-search-builder").FlowrSearchBuilder<"all", ["filter"], ParentInformation, import("../../search/flowr-search").FlowrSearchElements<ParentInformation, [] | import("../../search/flowr-search").FlowrSearchElement<ParentInformation>[]>>;
+    readonly createSearch: (config: UnusedDefinitionConfig) => import("../../search/flowr-search-builder").FlowrSearchBuilder<"all", ["filter"], ParentInformation, Promise<import("../../search/flowr-search").FlowrSearchElements<ParentInformation, [] | import("../../search/flowr-search").FlowrSearchElement<ParentInformation>[]>>>;
     readonly processSearchResult: (elements: import("../../search/flowr-search").FlowrSearchElements<ParentInformation, import("../../search/flowr-search").FlowrSearchElement<ParentInformation>[]>, config: UnusedDefinitionConfig, data: {
         normalize: NormalizedAst;
         dataflow: import("../../dataflow/info").DataflowInformation;
+        cfg: import("../../control-flow/control-flow-graph").ControlFlowInformation;
         config: import("../../config").FlowrConfigOptions;
     }) => {
         results: UnusedDefinitionResult[];

package/linter/rules/useless-loop.d.ts

@@ -16,10 +16,11 @@ export interface UselessLoopMetadata extends MergeableRecord {
     numOfUselessLoops: number;
 }
 export declare const USELESS_LOOP: {
-    readonly createSearch: () => import("../../search/flowr-search-builder").FlowrSearchBuilder<"all", ["filter"], import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../../search/flowr-search").FlowrSearchElements<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, [] | import("../../search/flowr-search").FlowrSearchElement<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>>;
-    readonly processSearchResult: (elements: import("../../search/flowr-search").FlowrSearchElements<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../../search/flowr-search").FlowrSearchElement<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>, config: UselessLoopConfig, data: {
+    readonly createSearch: () => import("../../search/flowr-search-builder").FlowrSearchBuilder<"all", ["filter"], import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, Promise<import("../../search/flowr-search").FlowrSearchElements<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, [] | import("../../search/flowr-search").FlowrSearchElement<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>>>;
+    readonly processSearchResult: (elements: import("../../search/flowr-search").FlowrSearchElements<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../../search/flowr-search").FlowrSearchElement<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>, useLessLoopConfig: UselessLoopConfig, { config, dataflow, normalize, cfg }: {
         normalize: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
         dataflow: import("../../dataflow/info").DataflowInformation;
+        cfg: import("../../control-flow/control-flow-graph").ControlFlowInformation;
         config: import("../../config").FlowrConfigOptions;
     }) => {
         results: {

package/linter/rules/useless-loop.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.USELESS_LOOP = void 0;
-const extract_cfg_1 = require("../../control-flow/extract-cfg");
 const useless_loop_1 = require("../../control-flow/useless-loop");
 const vertex_1 = require("../../dataflow/graph/vertex");
 const flowr_search_builder_1 = require("../../search/flowr-search-builder");
@@ -10,15 +9,14 @@ const linter_format_1 = require("../linter-format");
 const linter_tags_1 = require("../linter-tags");
 exports.USELESS_LOOP = {
     createSearch: () => flowr_search_builder_1.Q.all().filter(vertex_1.VertexType.FunctionCall),
-    processSearchResult: (elements, config, data) => {
-        const cfg = (0, extract_cfg_1.extractCfg)(data.normalize, data.config, data.dataflow.graph);
+    processSearchResult: (elements, useLessLoopConfig, { config, dataflow, normalize, cfg }) => {
         const results = elements.getElements().filter(e => {
-            const vertex = data.dataflow.graph.getVertex(e.node.info.id);
+            const vertex = dataflow.graph.getVertex(e.node.info.id);
             return vertex
                 && (0, vertex_1.isFunctionCallVertex)(vertex)
                 && vertex.origin !== 'unnamed'
-                && config.loopyFunctions.has(vertex.origin[0]);
-        }).filter(loop => (0, useless_loop_1.onlyLoopsOnce)(loop.node.info.id, data.dataflow.graph, cfg, data.normalize, data.config)).map(res => ({
+                && useLessLoopConfig.loopyFunctions.has(vertex.origin[0]);
+        }).filter(loop => (0, useless_loop_1.onlyLoopsOnce)(loop.node.info.id, dataflow.graph, cfg, normalize, config)).map(res => ({
             certainty: linter_format_1.LintingResultCertainty.Certain,
             name: res.node.lexeme,
             range: res.node.info.fullRange

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eagleoutice/flowr",
-  "version": "2.4.8",
+  "version": "2.6.0",
   "description": "Static Dataflow Analyzer and Program Slicer for the R Programming Language",
   "types": "dist/src/index.d.ts",
   "repository": {
@@ -30,6 +30,7 @@
     "wiki:normalized-ast": "ts-node src/documentation/print-normalized-ast-wiki.ts",
     "wiki:query-api": "ts-node src/documentation/print-query-wiki.ts",
     "wiki:core": "ts-node src/documentation/print-core-wiki.ts",
+    "wiki:analyzer": "ts-node src/documentation/print-analyzer-wiki.ts",
     "wiki:engines": "ts-node src/documentation/print-engines-wiki.ts",
     "wiki:search-api": "ts-node src/documentation/print-search-wiki.ts",
     "wiki:linting-and-testing": "ts-node src/documentation/print-linting-and-testing-wiki.ts",
@@ -183,6 +184,7 @@
     "@j-ulrich/release-it-regex-bumper": "^5.3.0",
     "@types/command-line-args": "^5.2.3",
     "@types/command-line-usage": "^5.0.4",
+    "@types/commonmark": "^0.27.10",
     "@types/n-readlines": "^1.0.6",
     "@types/n3": "^1.26.0",
     "@types/object-hash": "^3.0.6",
@@ -212,6 +214,8 @@
     "clipboardy": "^4.0.0",
     "command-line-args": "^6.0.1",
     "command-line-usage": "^7.0.3",
+    "commonmark": "^0.31.2",
+    "gray-matter": "^4.0.3",
     "joi": "^18.0.1",
     "lz-string": "^1.5.0",
     "n-readlines": "^1.0.1",

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

@@ -0,0 +1,93 @@
+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 { 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';
+interface FlowrAnalyzerCacheOptions<Parser extends KnownParser> {
+    parser: Parser;
+    config: FlowrConfigOptions;
+    request: RParseRequests;
+    getId?: IdGenerator<NoInfo>;
+    overwriteFilePath?: string;
+}
+type AnalyzerCacheType<Parser extends KnownParser> = Parser extends TreeSitterExecutor ? Partial<PipelineOutput<typeof TREE_SITTER_DATAFLOW_PIPELINE>> : Partial<PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>>;
+/**
+ * This provides the full analyzer caching layer, please avoid using this directly
+ * and prefer the {@link FlowrAnalyzer}.
+ */
+export declare class FlowrAnalyzerCache<Parser extends KnownParser> extends FlowrCache<AnalyzerCacheType<Parser>> {
+    private args;
+    private pipeline;
+    private controlFlowCache;
+    protected constructor(args: FlowrAnalyzerCacheOptions<Parser>);
+    private initCacheProviders;
+    static create<Parser extends KnownParser>(data: FlowrAnalyzerCacheOptions<Parser>): FlowrAnalyzerCache<Parser>;
+    receive(event: CacheInvalidationEvent): void;
+    private get;
+    reset(): void;
+    private runTapeUntil;
+    /**
+     * 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;
+    /**
+     * Get the normalized abstract syntax tree for the request, normalizing if necessary.
+     * @param force - Do not use the cache, instead force new analyses.
+     * @see {@link FlowrAnalyzerCache#peekNormalize} - to get the normalized AST if already available without triggering a new normalization.
+     */
+    normalize(force?: boolean): Promise<NonNullable<AnalyzerCacheType<Parser>['normalize']>>;
+    /**
+     * 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 useDataflow - Whether to use the dataflow graph for the creation of the CFG.
+     * @param simplifications - Simplification passes to be applied to the CFG.
+     */
+    controlflow(force: boolean | undefined, useDataflow: boolean, simplifications: readonly CfgSimplificationPassName[] | undefined): Promise<ControlFlowInformation>;
+    /**
+     * Get the control flow graph (CFG) for the request if already available, otherwise return `undefined`.
+     * @param useDataflow - Whether to use the dataflow graph for the creation of the CFG.
+     * @param simplifications - Simplification passes to be applied to the CFG.
+     *
+     * @see {@link FlowrAnalyzerCache#controlflow} - to get the control flow graph, computing if necessary.
+     */
+    peekControlflow(useDataflow: boolean, simplifications: readonly CfgSimplificationPassName[] | undefined): ControlFlowInformation | undefined;
+}
+export {};