@eagleoutice/flowr 2.2.13 → 2.2.15

package/documentation/print-query-wiki.js

@@ -34,6 +34,8 @@ const flowr_search_builder_1 = require("../search/flowr-search-builder");
 const vertex_1 = require("../dataflow/graph/vertex");
 const doc_types_1 = require("./doc-util/doc-types");
 const path_1 = __importDefault(require("path"));
+const control_flow_query_executor_1 = require("../queries/catalog/control-flow-query/control-flow-query-executor");
+const doc_cfg_1 = require("./doc-util/doc-cfg");
 (0, doc_query_1.registerQueryDocumentation)('call-context', {
     name: 'Call-Context Query',
     type: 'active',
@@ -477,6 +479,84 @@ Here, \`resolveValue\` tells the dependency query to resolve the value of this a
 		`;
     }
 });
+(0, doc_query_1.registerQueryDocumentation)('linter', {
+    name: 'Linter Query',
+    type: 'active',
+    shortDescription: 'Lints a given R script for common issues.',
+    functionName: dependencies_query_executor_1.executeDependenciesQuery.name,
+    functionFile: '../queries/catalog/linter-query/linter-query-executor.ts',
+    buildExplanation: async (shell) => {
+        const exampleCode = 'read.csv("i_do_not_exist.csv")';
+        return `
+This query lints a given R script for common issues, such as missing files, unused variables, and more.
+
+In other words, if you have a script simply reading: \`${exampleCode}\`, the following query returns all smells detected:
+${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
+                type: 'linter'
+            }], { showCode: false, collapseQuery: true })}
+
+You can also configure which rules to apply and what settings to use for these rules. 
+We welcome any feedback and suggestions for new rules on this (consider opening a [new issue](${doc_issue_1.NewIssueUrl})).
+		`;
+    }
+});
+(0, doc_query_1.registerQueryDocumentation)('control-flow', {
+    name: 'Control-Flow Query',
+    type: 'active',
+    shortDescription: 'Provides the control-flow of the program.',
+    functionName: control_flow_query_executor_1.executeControlFlowQuery.name,
+    functionFile: '../queries/catalog/control-flow-query/control-flow-query-executor.ts',
+    buildExplanation: async (shell) => {
+        const exampleCode = 'if(TRUE) 1 else 2';
+        return `
+This control-flow query provides you access to the control flow graph.
+
+In other words, if you have a script simply reading: \`${exampleCode}\`, the following query returns the CFG:
+${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
+                type: 'control-flow'
+            }], { showCode: false, collapseQuery: true, collapseResult: true })}
+
+You can also overwrite the simplification passes to tune the perspective. for example, if you want to have basic blocks:
+${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
+                type: 'control-flow',
+                config: {
+                    simplificationPasses: ['unique-cf-sets', 'to-basic-blocks']
+                }
+            }], { showCode: false, collapseResult: true })}
+
+this produces: 
+
+${await (0, doc_cfg_1.printCfgCode)(shell, exampleCode, { showCode: false, prefix: 'flowchart RL\n', simplifications: ['to-basic-blocks'] })}
+
+
+If, on the other hand, you want to prune dead code edges:
+${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
+                type: 'control-flow',
+                config: {
+                    simplificationPasses: ['unique-cf-sets', 'analyze-dead-code']
+                }
+            }], { showCode: false, collapseResult: true })}
+
+this produces:
+
+${await (0, doc_cfg_1.printCfgCode)(shell, exampleCode, { showCode: false, prefix: 'flowchart RL\n', simplifications: ['analyze-dead-code'] })}
+
+
+Or, completely remove dead code:
+${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
+                type: 'control-flow',
+                config: {
+                    simplificationPasses: ['unique-cf-sets', 'analyze-dead-code', 'remove-dead-code']
+                }
+            }], { showCode: false, collapseResult: true })}
+
+this produces:
+
+${await (0, doc_cfg_1.printCfgCode)(shell, exampleCode, { showCode: false, prefix: 'flowchart RL\n', simplifications: ['analyze-dead-code', 'remove-dead-code'] })}
+
+		`;
+    }
+});
 (0, doc_query_1.registerQueryDocumentation)('location-map', {
     name: 'Location Map Query',
     type: 'active',

package/linter/linter-executor.d.ts

@@ -0,0 +1,9 @@
+import type { LintingRuleConfig, LintingRuleNames } from './linter-rules';
+import type { NormalizedAst } from '../r-bridge/lang-4.x/ast/model/processing/decorate';
+import type { DataflowInformation } from '../dataflow/info';
+import type { LintingResults } from './linter-format';
+import type { DeepPartial } from 'ts-essentials';
+export declare function executeLintingRule<Name extends LintingRuleNames>(ruleName: Name, input: {
+    normalize: NormalizedAst;
+    dataflow: DataflowInformation;
+}, config?: DeepPartial<LintingRuleConfig<Name>>): LintingResults<Name>;

package/linter/linter-executor.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeLintingRule = executeLintingRule;
+const linter_rules_1 = require("./linter-rules");
+const flowr_search_executor_1 = require("../search/flowr-search-executor");
+const flowr_search_1 = require("../search/flowr-search");
+function executeLintingRule(ruleName, input, config) {
+    const rule = linter_rules_1.LintingRules[ruleName];
+    const fullConfig = { ...rule.defaultConfig, ...config };
+    const ruleSearch = rule.createSearch(fullConfig, input);
+    const searchStart = Date.now();
+    const searchResult = (0, flowr_search_executor_1.runSearch)(ruleSearch, input);
+    const searchTime = Date.now() - searchStart;
+    const processStart = Date.now();
+    const result = rule.processSearchResult(new flowr_search_1.FlowrSearchElements(searchResult), fullConfig, input);
+    const processTime = Date.now() - processStart;
+    return {
+        ...result,
+        '.meta': {
+            ...result['.meta'],
+            searchTimeMs: searchTime,
+            processTimeMs: processTime
+        }
+    };
+}
+//# sourceMappingURL=linter-executor.js.map

package/linter/linter-format.d.ts

@@ -0,0 +1,65 @@
+import type { FlowrSearchLike } from '../search/flowr-search-builder';
+import type { FlowrSearchElement, FlowrSearchElements } from '../search/flowr-search';
+import type { MergeableRecord } from '../util/objects';
+import type { GeneratorNames } from '../search/search-executor/search-generators';
+import type { TransformerNames } from '../search/search-executor/search-transformer';
+import type { NormalizedAst, ParentInformation } from '../r-bridge/lang-4.x/ast/model/processing/decorate';
+import type { LintingRuleConfig, LintingRuleMetadata, LintingRuleNames, LintingRuleResult } from './linter-rules';
+import type { DataflowInformation } from '../dataflow/info';
+import type { DeepPartial } from 'ts-essentials';
+/**
+ * The base interface for a linting rule, which contains all of its relevant settings.
+ * The registry of valid linting rules is stored in {@link LintingRules}.
+ */
+export interface LintingRule<Result extends LintingResult, Metadata extends MergeableRecord, Config extends MergeableRecord = never, Info = ParentInformation, Elements extends FlowrSearchElement<Info>[] = FlowrSearchElement<Info>[]> {
+    /**
+     * Creates a flowR search that will then be executed and whose results will be passed to {@link processSearchResult}.
+     * In the future, additional optimizations and transformations may be applied to the search between this function and {@link processSearchResult}.
+     */
+    readonly createSearch: (config: Config, data: {
+        normalize: NormalizedAst;
+        dataflow: DataflowInformation;
+    }) => FlowrSearchLike<Info, GeneratorNames, TransformerNames[], FlowrSearchElements<Info, Elements>>;
+    /**
+     * Processes the search results of the search created through {@link createSearch}.
+     * This function is expected to return the linting results from this rule for the given search, ie usually the given script file.
+     */
+    readonly processSearchResult: (elements: FlowrSearchElements<Info, Elements>, config: Config, data: {
+        normalize: NormalizedAst;
+        dataflow: DataflowInformation;
+    }) => {
+        results: Result[];
+        '.meta': Metadata;
+    };
+    /**
+     * A function used to pretty-print the given linting result.
+     * By default, the {@link LintingResult#certainty} is automatically printed alongside this information.
+     */
+    readonly prettyPrint: (result: Result, metadata: Metadata) => string;
+    /**
+     * The default config for this linting rule.
+     * The default config is combined with the user config when executing the rule.
+     */
+    readonly defaultConfig: NoInfer<Config>;
+}
+/**
+ * A linting result for a single linting rule match.
+ */
+export interface LintingResult {
+    readonly certainty: LintingCertainty;
+}
+export interface ConfiguredLintingRule<Name extends LintingRuleNames = LintingRuleNames> {
+    readonly name: Name;
+    readonly config: DeepPartial<LintingRuleConfig<Name>>;
+}
+export interface LintingResults<Name extends LintingRuleNames> {
+    results: LintingRuleResult<Name>[];
+    '.meta': LintingRuleMetadata<Name> & {
+        readonly searchTimeMs: number;
+        readonly processTimeMs: number;
+    };
+}
+export declare enum LintingCertainty {
+    Maybe = "maybe",
+    Definitely = "definitely"
+}

package/linter/linter-format.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LintingCertainty = void 0;
+var LintingCertainty;
+(function (LintingCertainty) {
+    LintingCertainty["Maybe"] = "maybe";
+    LintingCertainty["Definitely"] = "definitely";
+})(LintingCertainty || (exports.LintingCertainty = LintingCertainty = {}));
+//# sourceMappingURL=linter-format.js.map

package/linter/linter-rules.d.ts

@@ -0,0 +1,42 @@
+import type { LintingRule } from './linter-format';
+/**
+ * The registry of currently supported linting rules.
+ * A linting rule can be executed on a dataflow pipeline result using {@link executeLintingRule}.
+ */
+export declare const LintingRules: {
+    readonly 'deprecated-functions': {
+        readonly createSearch: (_config: import("./rules/1-deprecated-functions").DeprecatedFunctionsConfig) => import("../search/flowr-search-builder").FlowrSearchBuilder<"all", ["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/search-executor/search-enrichers").EnrichedFlowrSearchElement<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: import("./rules/1-deprecated-functions").DeprecatedFunctionsConfig) => {
+            results: {
+                certainty: import("./linter-format").LintingCertainty.Definitely;
+                function: import("../dataflow/environments/identifier").Identifier;
+                range: import("../util/range").SourceRange;
+            }[];
+            '.meta': import("./rules/1-deprecated-functions").DeprecatedFunctionsMetadata;
+        };
+        readonly prettyPrint: (result: import("./rules/1-deprecated-functions").DeprecatedFunctionsResult) => string;
+        readonly defaultConfig: {
+            readonly 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"];
+        };
+    };
+    readonly 'file-path-validity': {
+        readonly createSearch: (config: import("./rules/2-file-path-validity").FilePathValidityConfig) => import("../search/flowr-search-builder").FlowrSearchBuilder<"from-query", [], 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").FlowrSearchElementFromQuery<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").FlowrSearchElementFromQuery<import("../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>, config: import("./rules/2-file-path-validity").FilePathValidityConfig, data: {
+            normalize: import("../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
+            dataflow: import("../dataflow/info").DataflowInformation;
+        }) => {
+            results: import("./rules/2-file-path-validity").FilePathValidityResult[];
+            ".meta": import("./rules/2-file-path-validity").FilePathValidityMetadata;
+        };
+        readonly prettyPrint: (result: import("./rules/2-file-path-validity").FilePathValidityResult) => string;
+        readonly defaultConfig: {
+            readonly additionalReadFunctions: [];
+            readonly additionalWriteFunctions: [];
+            readonly includeUnknown: false;
+        };
+    };
+};
+export type LintingRuleNames = keyof typeof LintingRules;
+export type LintingRuleMetadata<Name extends LintingRuleNames> = typeof LintingRules[Name] extends LintingRule<infer _Result, infer Metadata, infer _Config, infer _Info, infer _Elements> ? Metadata : never;
+export type LintingRuleResult<Name extends LintingRuleNames> = typeof LintingRules[Name] extends LintingRule<infer Result, infer _Metadata, infer _Config, infer _Info, infer _Elements> ? Result : never;
+export type LintingRuleConfig<Name extends LintingRuleNames> = typeof LintingRules[Name] extends LintingRule<infer _Result, infer _Metadata, infer Config, infer _Info, infer _Elements> ? Config : never;

package/linter/linter-rules.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LintingRules = void 0;
+const _1_deprecated_functions_1 = require("./rules/1-deprecated-functions");
+const _2_file_path_validity_1 = require("./rules/2-file-path-validity");
+/**
+ * The registry of currently supported linting rules.
+ * A linting rule can be executed on a dataflow pipeline result using {@link executeLintingRule}.
+ */
+exports.LintingRules = {
+    'deprecated-functions': _1_deprecated_functions_1.R1_DEPRECATED_FUNCTIONS,
+    'file-path-validity': _2_file_path_validity_1.R2_FILE_PATH_VALIDITY
+};
+//# sourceMappingURL=linter-rules.js.map

package/linter/rules/1-deprecated-functions.d.ts

@@ -0,0 +1,34 @@
+import type { LintingResult } from '../linter-format';
+import { LintingCertainty } from '../linter-format';
+import type { MergeableRecord } from '../../util/objects';
+import type { SourceRange } from '../../util/range';
+import type { Identifier } from '../../dataflow/environments/identifier';
+export interface DeprecatedFunctionsResult extends LintingResult {
+    function: string;
+    range: SourceRange;
+}
+export interface DeprecatedFunctionsConfig extends MergeableRecord {
+    /**
+     * The list of function names that should be marked as deprecated.
+     */
+    deprecatedFunctions: string[];
+}
+export interface DeprecatedFunctionsMetadata extends MergeableRecord {
+    totalRelevant: number;
+    totalNotDeprecated: number;
+}
+export declare const R1_DEPRECATED_FUNCTIONS: {
+    readonly createSearch: (_config: DeprecatedFunctionsConfig) => import("../../search/flowr-search-builder").FlowrSearchBuilder<"all", ["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/search-executor/search-enrichers").EnrichedFlowrSearchElement<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: DeprecatedFunctionsConfig) => {
+        results: {
+            certainty: LintingCertainty.Definitely;
+            function: Identifier;
+            range: SourceRange;
+        }[];
+        '.meta': DeprecatedFunctionsMetadata;
+    };
+    readonly prettyPrint: (result: DeprecatedFunctionsResult) => string;
+    readonly defaultConfig: {
+        readonly 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"];
+    };
+};

package/linter/rules/1-deprecated-functions.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.R1_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");
+exports.R1_DEPRECATED_FUNCTIONS = {
+    createSearch: (_config) => flowr_search_builder_1.Q.all().with(search_enrichers_1.Enrichment.CallTargets),
+    processSearchResult: (elements, config) => {
+        const metadata = {
+            totalRelevant: 0,
+            totalNotDeprecated: 0
+        };
+        return {
+            results: elements.getElements()
+                .flatMap(element => {
+                const targets = (0, search_enrichers_1.enrichmentContent)(element, search_enrichers_1.Enrichment.CallTargets).targets;
+                // if there is a call target that is not built-in (ie a custom function), we don't want to mark it as deprecated
+                // eventually we'd want to solve this with an argument to the CallTargets enrichment like satisfiesCallTargets does!
+                if (targets.some(t => typeof t !== 'string')) {
+                    return [];
+                }
+                return targets.map(target => {
+                    metadata.totalRelevant++;
+                    return {
+                        range: element.node.info.fullRange,
+                        target: target
+                    };
+                });
+            })
+                .filter(element => {
+                if (config.deprecatedFunctions.includes(element.target)) {
+                    return true;
+                }
+                else {
+                    metadata.totalNotDeprecated++;
+                    return false;
+                }
+            })
+                .map(element => ({
+                certainty: linter_format_1.LintingCertainty.Definitely,
+                function: element.target,
+                range: element.range
+            })),
+            '.meta': metadata
+        };
+    },
+    prettyPrint: result => `Function \`${result.function}\` at ${(0, dfg_1.formatRange)(result.range)}`,
+    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',]
+    }
+};
+//# sourceMappingURL=1-deprecated-functions.js.map

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

@@ -0,0 +1,48 @@
+import type { LintingResult } from '../linter-format';
+import type { MergeableRecord } from '../../util/objects';
+import type { SourceRange } from '../../util/range';
+import type { ParentInformation } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
+import type { FlowrSearchElementFromQuery } from '../../search/flowr-search';
+import type { FunctionInfo } from '../../queries/catalog/dependencies-query/function-info/function-info';
+export interface FilePathValidityResult extends LintingResult {
+    filePath: string;
+    range: SourceRange;
+}
+export interface FilePathValidityConfig extends MergeableRecord {
+    /**
+     * The set of functions that should additionally be considered as reading a file path.
+     * Entries in this array use the {@link FunctionInfo} format from the dependencies query.
+     */
+    additionalReadFunctions: FunctionInfo[];
+    /**
+     * The set of functions that should additionally be considered as writing to a file path.
+     * Entries in this array use the {@link FunctionInfo} format from the dependencies query.
+     */
+    additionalWriteFunctions: FunctionInfo[];
+    /**
+     * Whether unknown file paths should be included as linting results.
+     */
+    includeUnknown: boolean;
+}
+export interface FilePathValidityMetadata extends MergeableRecord {
+    totalReads: number;
+    totalUnknown: number;
+    totalWritesBeforeAlways: number;
+    totalValid: number;
+}
+export declare const R2_FILE_PATH_VALIDITY: {
+    readonly createSearch: (config: FilePathValidityConfig) => import("../../search/flowr-search-builder").FlowrSearchBuilder<"from-query", [], ParentInformation, import("../../search/flowr-search").FlowrSearchElements<ParentInformation, FlowrSearchElementFromQuery<ParentInformation>[]>>;
+    readonly processSearchResult: (elements: import("../../search/flowr-search").FlowrSearchElements<ParentInformation, FlowrSearchElementFromQuery<ParentInformation>[]>, config: FilePathValidityConfig, data: {
+        normalize: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
+        dataflow: import("../../dataflow/info").DataflowInformation;
+    }) => {
+        results: FilePathValidityResult[];
+        ".meta": FilePathValidityMetadata;
+    };
+    readonly prettyPrint: (result: FilePathValidityResult) => string;
+    readonly defaultConfig: {
+        readonly additionalReadFunctions: [];
+        readonly additionalWriteFunctions: [];
+        readonly includeUnknown: false;
+    };
+};

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

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.R2_FILE_PATH_VALIDITY = 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 dependencies_query_format_1 = require("../../queries/catalog/dependencies-query/dependencies-query-format");
+const built_in_source_1 = require("../../dataflow/internal/process/functions/call/built-in/built-in-source");
+const logic_1 = require("../../util/logic");
+const config_1 = require("../../config");
+const retriever_1 = require("../../r-bridge/retriever");
+const read_functions_1 = require("../../queries/catalog/dependencies-query/function-info/read-functions");
+const write_functions_1 = require("../../queries/catalog/dependencies-query/function-info/write-functions");
+const extract_cfg_1 = require("../../control-flow/extract-cfg");
+const happens_before_1 = require("../../control-flow/happens-before");
+exports.R2_FILE_PATH_VALIDITY = {
+    createSearch: (config) => flowr_search_builder_1.Q.fromQuery({
+        type: 'dependencies',
+        // we only want to check read and write functions, so we explicitly clear all others
+        ignoreDefaultFunctions: true,
+        readFunctions: read_functions_1.ReadFunctions.concat(config.additionalReadFunctions),
+        writeFunctions: write_functions_1.WriteFunctions.concat(config.additionalWriteFunctions)
+    }),
+    processSearchResult: (elements, config, data) => {
+        const cfg = (0, extract_cfg_1.extractSimpleCfg)(data.normalize).graph;
+        const metadata = {
+            totalReads: 0,
+            totalUnknown: 0,
+            totalWritesBeforeAlways: 0,
+            totalValid: 0
+        };
+        return {
+            results: elements.getElements().flatMap(element => {
+                const results = element.queryResult;
+                const matchingRead = results.readData.find(r => r.nodeId == element.node.info.id);
+                if (!matchingRead) {
+                    return [];
+                }
+                metadata.totalReads++;
+                const range = element.node.info.fullRange;
+                // check if we can't parse the file path statically
+                if (matchingRead.source === dependencies_query_format_1.Unknown) {
+                    metadata.totalUnknown++;
+                    if (config.includeUnknown) {
+                        return [{
+                                range,
+                                filePath: dependencies_query_format_1.Unknown,
+                                certainty: linter_format_1.LintingCertainty.Maybe
+                            }];
+                    }
+                    else {
+                        return [];
+                    }
+                }
+                // check if any write to the same file happens before the read, and exclude this case if so
+                const writesToFile = results.writtenData.filter(r => samePath(r.destination, matchingRead.source));
+                const writesBefore = writesToFile.map(w => (0, happens_before_1.happensBefore)(cfg, w.nodeId, element.node.info.id));
+                if (writesBefore.some(w => w === logic_1.Ternary.Always)) {
+                    metadata.totalWritesBeforeAlways++;
+                    return [];
+                }
+                // check if the file exists!
+                const paths = (0, built_in_source_1.findSource)(matchingRead.source, {
+                    referenceChain: element.node.info.file ? [(0, retriever_1.requestFromInput)(`file://${element.node.info.file}`)] : []
+                });
+                if (paths && paths.length) {
+                    metadata.totalValid++;
+                    return [];
+                }
+                return [{
+                        range,
+                        filePath: matchingRead.source,
+                        certainty: writesBefore && writesBefore.length && writesBefore.every(w => w === logic_1.Ternary.Maybe) ? linter_format_1.LintingCertainty.Maybe : linter_format_1.LintingCertainty.Definitely
+                    }];
+            }),
+            '.meta': metadata
+        };
+    },
+    prettyPrint: result => `Path \`${result.filePath}\` at ${(0, dfg_1.formatRange)(result.range)}`,
+    defaultConfig: {
+        additionalReadFunctions: [],
+        additionalWriteFunctions: [],
+        includeUnknown: false
+    }
+};
+function samePath(a, b) {
+    if ((0, config_1.getConfig)().solver.resolveSource?.ignoreCapitalization === true) {
+        a = a.toLowerCase();
+        b = b.toLowerCase();
+    }
+    return a === b;
+}
+//# sourceMappingURL=2-file-path-validity.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eagleoutice/flowr",
-  "version": "2.2.13",
+  "version": "2.2.15",
   "description": "Static Dataflow Analyzer and Program Slicer for the R Programming Language",
   "types": "dist/src/index.d.ts",
   "repository": {
@@ -37,6 +37,7 @@
     "wiki:onboarding": "ts-node src/documentation/print-onboarding-wiki.ts",
     "wiki:faq": "ts-node src/documentation/print-faq-wiki.ts",
     "wiki:cfg": "ts-node src/documentation/print-cfg-wiki.ts",
+    "wiki:linter": "ts-node src/documentation/print-linter-wiki.ts",
     "gen:readme": "ts-node src/documentation/print-readme.ts",
     "build": "tsc --project .",
     "build-dev": "npm run build && npm run build:copy-wasm",

package/queries/catalog/call-context-query/call-context-query-executor.js

@@ -180,7 +180,7 @@ function executeCallContextQueries({ dataflow: { graph }, ast }, queries) {
     const { promotedQueries, requiresCfg } = promoteQueryCallNames(queries);
     let cfg = undefined;
     if (requiresCfg) {
-        cfg = (0, extract_cfg_1.extractCFG)(ast, graph, []);
+        cfg = (0, extract_cfg_1.extractCfg)(ast, graph, []);
     }
     const queriesWhichWantAliases = promotedQueries.filter(q => q.includeAliases);
     for (const [nodeId, info] of graph.vertices(true)) {

package/queries/catalog/call-context-query/call-context-query-format.d.ts

@@ -56,7 +56,7 @@ export interface DefaultCallContextQueryFormat<RegexType extends RegExp | string
  * For now, this uses the static Control-Flow-Graph produced by flowR as the FD over-approximation is still not stable (see #1005).
  * In short, this means that we are unable to detect origins over function call boundaries but plan on being more precise in the future.
  */
-interface LinkToLastCall<CallName extends RegExp | string = RegExp | string> extends BaseQueryFormat {
+export interface LinkToLastCall<CallName extends RegExp | string = RegExp | string> extends BaseQueryFormat {
     readonly type: 'link-to-last-call';
     /** Regex regarding the function name of the last call. Similar to {@link DefaultCallContextQueryFormat#callName}, strings are interpreted as a `RegExp`. */
     readonly callName: CallName;
@@ -110,5 +110,5 @@ export declare const CallContextQueryDefinition: {
     readonly executor: typeof executeCallContextQueries;
     readonly asciiSummarizer: (formatter: OutputFormatter, processed: PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>, queryResults: BaseQueryResult, result: string[]) => boolean;
     readonly schema: Joi.ObjectSchema<any>;
+    readonly flattenInvolvedNodes: (queryResults: BaseQueryResult) => NodeId[];
 };
-export {};

package/queries/catalog/call-context-query/call-context-query-format.js

@@ -39,6 +39,10 @@ exports.CallContextQueryDefinition = {
             includeUndefinedFiles: joi_1.default.boolean().optional().description('If `fileFilter` is set, but a nodes `file` attribute is `undefined`, should we include it in the results? Defaults to `true`.')
         }).optional().description('Filter that, when set, a node\'s file attribute must match to be considered'),
         linkTo: joi_1.default.alternatives(CallContextQueryLinkTo, joi_1.default.array().items(CallContextQueryLinkTo)).optional().description('Links the current call to the last call of the given kind. This way, you can link a call like `points` to the latest graphics plot etc.')
-    }).description('Call context query used to find calls in the dataflow graph')
+    }).description('Call context query used to find calls in the dataflow graph'),
+    flattenInvolvedNodes: (queryResults) => {
+        const out = queryResults;
+        return Object.values(out.kinds).flatMap(({ subkinds }) => Object.values(subkinds).flatMap(subkinds => subkinds.map(subkind => subkind.id)));
+    }
 };
 //# sourceMappingURL=call-context-query-format.js.map

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

@@ -2,6 +2,7 @@ import type { BaseQueryFormat, BaseQueryResult } from '../../base-query-format';
 import Joi from 'joi';
 import type { DataflowGraphClusters } from '../../../dataflow/cluster';
 import { executeDataflowClusterQuery } from './cluster-query-executor';
+import type { NodeId } from '../../../r-bridge/lang-4.x/ast/model/processing/node-id';
 /**
  * Calculates and returns all clusters encountered in the dataflow graph.
  */
@@ -69,4 +70,5 @@ export declare const ClusterQueryDefinition: {
         readonly dependencies: readonly ["normalize"];
     }>>, queryResults: BaseQueryResult, result: string[]) => true;
     readonly schema: Joi.ObjectSchema<any>;
+    readonly flattenInvolvedNodes: (queryResults: BaseQueryResult) => NodeId[];
 };

package/queries/catalog/cluster-query/cluster-query-format.js

@@ -27,6 +27,10 @@ exports.ClusterQueryDefinition = {
     },
     schema: joi_1.default.object({
         type: joi_1.default.string().valid('dataflow-cluster').required().description('The type of the query.'),
-    }).description('The cluster query calculates and returns all clusters in the dataflow graph.')
+    }).description('The cluster query calculates and returns all clusters in the dataflow graph.'),
+    flattenInvolvedNodes: (queryResults) => {
+        const out = queryResults;
+        return out.clusters.flatMap(({ members }) => members);
+    }
 };
 //# sourceMappingURL=cluster-query-format.js.map

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

@@ -13,4 +13,5 @@ export declare const ConfigQueryDefinition: {
     readonly executor: typeof executeConfigQuery;
     readonly asciiSummarizer: (formatter: OutputFormatter, _processed: unknown, queryResults: BaseQueryResult, result: string[]) => boolean;
     readonly schema: Joi.ObjectSchema<any>;
+    readonly flattenInvolvedNodes: () => never[];
 };

package/queries/catalog/config-query/config-query-format.js

@@ -19,6 +19,7 @@ exports.ConfigQueryDefinition = {
     },
     schema: joi_1.default.object({
         type: joi_1.default.string().valid('config').required().description('The type of the query.'),
-    }).description('The config query retrieves the current configuration of the flowR instance.')
+    }).description('The config query retrieves the current configuration of the flowR instance.'),
+    flattenInvolvedNodes: () => []
 };
 //# sourceMappingURL=config-query-format.js.map

package/queries/catalog/control-flow-query/control-flow-query-executor.d.ts

@@ -0,0 +1,3 @@
+import type { ControlFlowQuery, ControlFlowQueryResult } from './control-flow-query-format';
+import type { BasicQueryData } from '../../base-query-format';
+export declare function executeControlFlowQuery({ dataflow: { graph }, ast }: BasicQueryData, queries: readonly ControlFlowQuery[]): ControlFlowQueryResult;