@eagleoutice/flowr 2.2.16 → 2.4.0

package/linter/rules/unused-definition.js

@@ -80,7 +80,7 @@ exports.UNUSED_DEFINITION = {
                 // found an unused definition
                 const variableName = element.node.lexeme;
                 return [{
-                        certainty: linter_format_1.LintingCertainty.Maybe,
+                        certainty: linter_format_1.LintingResultCertainty.Uncertain,
                         variableName,
                         range: element.node.info.fullRange ?? element.node.location ?? (0, range_1.rangeFrom)(-1, -1, -1, -1),
                         quickFix: buildQuickFix(element.node, data.dataflow.graph, data.normalize)
@@ -97,6 +97,8 @@ exports.UNUSED_DEFINITION = {
         name: 'Unused Definitions',
         description: 'Checks for unused definitions.',
         tags: [linter_tags_1.LintingRuleTag.Readability, linter_tags_1.LintingRuleTag.Smell, linter_tags_1.LintingRuleTag.QuickFix],
+        // our limited analysis causes unused definitions involving complex reflection etc. not to be included in our result, but unused definitions are correctly validated
+        certainty: linter_format_1.LintingRuleCertainty.BestEffort,
         defaultConfig: {
             includeFunctionDefinitions: true
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eagleoutice/flowr",
-  "version": "2.2.16",
+  "version": "2.4.0",
   "description": "Static Dataflow Analyzer and Program Slicer for the R Programming Language",
   "types": "dist/src/index.d.ts",
   "repository": {
@@ -176,7 +176,7 @@
   "devDependencies": {
     "@commitlint/cli": "^19.7.1",
     "@commitlint/config-angular": "^19.7.1",
-    "@eagleoutice/eslint-config-flowr": "^1.0.17",
+    "@eagleoutice/eslint-config-flowr": "^1.0.19",
     "@eslint/eslintrc": "^3.2.0",
     "@eslint/js": "^9.20.0",
     "@j-ulrich/release-it-regex-bumper": "^5.3.0",

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

@@ -40,7 +40,12 @@ function executeDependenciesQuery(data, queries) {
     const readFunctions = getFunctionsToCheck(query.readFunctions, ignoreDefault, read_functions_1.ReadFunctions);
     const writeFunctions = getFunctionsToCheck(query.writeFunctions, ignoreDefault, write_functions_1.WriteFunctions);
     const numberOfFunctions = libraryFunctions.length + sourceFunctions.length + readFunctions.length + writeFunctions.length;
-    const results = numberOfFunctions === 0 ? { kinds: {}, '.meta': { timing: 0 } } : (0, query_1.executeQueriesOfSameType)(data, ...makeCallContextQuery(libraryFunctions, 'library'), ...makeCallContextQuery(sourceFunctions, 'source'), ...makeCallContextQuery(readFunctions, 'read'), ...makeCallContextQuery(writeFunctions, 'write'));
+    const results = numberOfFunctions === 0 ? { kinds: {}, '.meta': { timing: 0 } } : (0, query_1.executeQueriesOfSameType)(data, [
+        makeCallContextQuery(libraryFunctions, 'library'),
+        makeCallContextQuery(sourceFunctions, 'source'),
+        makeCallContextQuery(readFunctions, 'read'),
+        makeCallContextQuery(writeFunctions, 'write')
+    ].flat());
     function getLexeme(argument, id) {
         if ((argument && argument !== dependencies_query_format_1.Unknown) || !id) {
             return undefined;

package/queries/catalog/dependencies-query/function-info/read-functions.js

@@ -97,5 +97,6 @@ exports.ReadFunctions = [
     { package: 'stats', name: 'read.ftable', argIdx: 0, argName: 'file', resolveValue: true },
     { package: 'DBI', name: 'dbReadTable', argIdx: 1, argName: 'name', resolveValue: true },
     { package: 'DBI', name: 'dbReadTableArrow', argIdx: 1, argName: 'name', resolveValue: true },
+    { package: 'jsonlite', name: 'read_json', argIdx: 0, argName: 'path', resolveValue: true },
 ];
 //# sourceMappingURL=read-functions.js.map

package/queries/catalog/dependencies-query/function-info/write-functions.js

@@ -83,5 +83,6 @@ exports.WriteFunctions = [
     { package: 'rasterpdf', name: 'raster_pdf', argIdx: 0, argName: 'filename', resolveValue: true },
     { package: 'rasterpdf', name: 'agg_pdf', argIdx: 0, argName: 'filename', resolveValue: true },
     { package: 'highcharter', name: 'hc_exporting', argName: 'filename', resolveValue: true },
+    { package: 'jsonlite', name: 'write_json', argIdx: 1, argName: 'path', resolveValue: true },
 ];
 //# sourceMappingURL=write-functions.js.map

package/queries/catalog/df-shape-query/df-shape-query-executor.d.ts

@@ -0,0 +1,3 @@
+import type { DfShapeQuery, DfShapeQueryResult } from './df-shape-query-format';
+import type { BasicQueryData } from '../../base-query-format';
+export declare function executeDfShapeQuery({ dataflow: { graph }, ast, config }: BasicQueryData, queries: readonly DfShapeQuery[]): DfShapeQueryResult;

package/queries/catalog/df-shape-query/df-shape-query-executor.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeDfShapeQuery = executeDfShapeQuery;
+const log_1 = require("../../../util/log");
+const extract_cfg_1 = require("../../../control-flow/extract-cfg");
+const shape_inference_1 = require("../../../abstract-interpretation/data-frame/shape-inference");
+const parse_1 = require("../../../slicing/criterion/parse");
+function executeDfShapeQuery({ dataflow: { graph }, ast, config }, queries) {
+    if (queries.length !== 1 && queries.some(query => query.criterion === undefined)) {
+        log_1.log.warn('The dataframe shape query expects only up to one query without slicing criterion, but got', queries.length);
+        queries = [{ type: 'df-shape' }];
+    }
+    const start = Date.now();
+    const cfg = (0, extract_cfg_1.extractCfg)(ast, config, graph);
+    const domains = (0, shape_inference_1.inferDataFrameShapes)(cfg, graph, ast, config);
+    if (queries.length === 1 && queries[0].criterion === undefined) {
+        return {
+            '.meta': {
+                timing: Date.now() - start
+            },
+            domains: domains
+        };
+    }
+    const result = new Map();
+    for (const query of queries) {
+        if (query.criterion === undefined) {
+            log_1.log.warn('Missing criterion in dataframe shape query');
+            continue;
+        }
+        else if (result.has(query.criterion)) {
+            log_1.log.warn('Duplicate criterion in dataframe shape query:', query.criterion);
+            continue;
+        }
+        const nodeId = (0, parse_1.slicingCriterionToId)(query.criterion, ast.idMap);
+        const node = ast.idMap.get(nodeId);
+        const value = (0, shape_inference_1.resolveIdToDataFrameShape)(node?.info.id, graph);
+        result.set(query.criterion, value);
+    }
+    return {
+        '.meta': {
+            timing: Date.now() - start
+        },
+        domains: result
+    };
+}
+//# sourceMappingURL=df-shape-query-executor.js.map

package/queries/catalog/df-shape-query/df-shape-query-format.d.ts

@@ -0,0 +1,72 @@
+import type { BaseQueryFormat, BaseQueryResult } from '../../base-query-format';
+import Joi from 'joi';
+import type { DataFrameDomain, DataFrameStateDomain } from '../../../abstract-interpretation/data-frame/domain';
+import { executeDfShapeQuery } from './df-shape-query-executor';
+import type { SingleSlicingCriterion } from '../../../slicing/criterion/parse';
+/** Infer the shape of data frames using abstract interpretation. */
+export interface DfShapeQuery extends BaseQueryFormat {
+    readonly type: 'df-shape';
+    readonly criterion?: SingleSlicingCriterion;
+}
+export interface DfShapeQueryResult extends BaseQueryResult {
+    domains: DataFrameStateDomain | Map<SingleSlicingCriterion, DataFrameDomain | undefined>;
+}
+export declare const DfShapeQueryDefinition: {
+    readonly executor: typeof executeDfShapeQuery;
+    readonly asciiSummarizer: (formatter: import("../../../util/text/ansi").OutputFormatter, _processed: import("../../../core/steps/pipeline/pipeline").PipelineOutput<import("../../../core/steps/pipeline/pipeline").Pipeline<{
+        readonly name: "parse";
+        readonly humanReadableName: "parse with R shell";
+        readonly description: "Parse the given R code into an AST";
+        readonly processor: (_results: unknown, input: Partial<import("../../../r-bridge/parser").ParseRequiredInput<string>>) => Promise<import("../../../r-bridge/parser").ParseStepOutput<string>>;
+        readonly executed: import("../../../core/steps/pipeline-step").PipelineStepStage.OncePerFile;
+        readonly printer: {
+            readonly 0: typeof import("../../../core/print/print").internalPrinter;
+            readonly 2: {
+                (value: any, replacer?: (this: any, key: string, value: any) => any, space?: string | number): string;
+                (value: any, replacer?: (number | string)[] | null, space?: string | number): string;
+            };
+            readonly 5: ({ parsed }: import("../../../r-bridge/parser").ParseStepOutput<string>, config: import("../../../util/quads").QuadSerializationConfiguration) => string;
+        };
+        readonly dependencies: readonly [];
+        readonly requiredInput: import("../../../r-bridge/parser").ParseRequiredInput<string>;
+    } | {
+        readonly name: "normalize";
+        readonly humanReadableName: "normalize";
+        readonly description: "Normalize the AST to flowR's AST";
+        readonly processor: (results: {
+            parse?: import("../../../r-bridge/parser").ParseStepOutput<string>;
+        }, input: Partial<import("../../../core/steps/all/core/10-normalize").NormalizeRequiredInput>) => import("../../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst<import("../../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../../../r-bridge/lang-4.x/ast/model/model").RNode<import("../../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>>;
+        readonly executed: import("../../../core/steps/pipeline-step").PipelineStepStage.OncePerFile;
+        readonly printer: {
+            readonly 0: typeof import("../../../core/print/print").internalPrinter;
+            readonly 2: typeof import("../../../core/print/normalize-printer").normalizedAstToJson;
+            readonly 5: typeof import("../../../core/print/normalize-printer").normalizedAstToQuads;
+            readonly 3: typeof import("../../../core/print/normalize-printer").printNormalizedAstToMermaid;
+            readonly 4: typeof import("../../../core/print/normalize-printer").printNormalizedAstToMermaidUrl;
+        };
+        readonly dependencies: readonly ["parse"];
+        readonly requiredInput: import("../../../core/steps/all/core/10-normalize").NormalizeRequiredInput;
+    } | {
+        readonly humanReadableName: "dataflow";
+        readonly processor: (results: {
+            normalize?: import("../../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
+        }, input: {
+            request?: import("../../../r-bridge/retriever").RParseRequests;
+            parser?: import("../../../r-bridge/parser").Parser<import("../../../r-bridge/parser").KnownParserType>;
+        }, config: import("../../../config").FlowrConfigOptions) => import("../../../dataflow/info").DataflowInformation;
+        readonly requiredInput: {};
+        readonly name: "dataflow";
+        readonly description: "Construct the dataflow graph";
+        readonly executed: import("../../../core/steps/pipeline-step").PipelineStepStage.OncePerFile;
+        readonly printer: {
+            readonly 0: typeof import("../../../core/print/print").internalPrinter;
+            readonly 2: typeof import("../../../core/print/dataflow-printer").dataflowGraphToJson;
+            readonly 5: typeof import("../../../core/print/dataflow-printer").dataflowGraphToQuads;
+            readonly 3: typeof import("../../../core/print/dataflow-printer").dataflowGraphToMermaid;
+            readonly 4: typeof import("../../../core/print/dataflow-printer").dataflowGraphToMermaidUrl;
+        };
+        readonly dependencies: readonly ["normalize"];
+    }>>, queryResults: BaseQueryResult, result: string[]) => true;
+    readonly schema: Joi.ObjectSchema<any>;
+    readonly flattenInvolvedNodes: () => never[];
+};

package/queries/catalog/df-shape-query/df-shape-query-format.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DfShapeQueryDefinition = void 0;
+const ansi_1 = require("../../../util/text/ansi");
+const time_1 = require("../../../util/text/time");
+const joi_1 = __importDefault(require("joi"));
+const df_shape_query_executor_1 = require("./df-shape-query-executor");
+const json_1 = require("../../../util/json");
+exports.DfShapeQueryDefinition = {
+    executor: df_shape_query_executor_1.executeDfShapeQuery,
+    asciiSummarizer: (formatter, _processed, queryResults, result) => {
+        const out = queryResults;
+        result.push(`Query: ${(0, ansi_1.bold)('df-shape', formatter)} (${(0, time_1.printAsMs)(out['.meta'].timing, 0)})`);
+        result.push(...out.domains.entries().take(20).map(([key, domain]) => {
+            return `   ╰ ${key}: ${JSON.stringify(domain, json_1.jsonReplacer)}`;
+        }));
+        if (out.domains.size > 20) {
+            result.push('   ╰ ... (see JSON)');
+        }
+        return true;
+    },
+    schema: joi_1.default.object({
+        type: joi_1.default.string().valid('df-shape').required().description('The type of the query.'),
+        criterion: joi_1.default.string().optional().description('The slicing criterion of the node to get the dataframe shape for.')
+    }).description('The df-shape query retrieves information on the shape of dataframes'),
+    flattenInvolvedNodes: () => []
+};
+//# sourceMappingURL=df-shape-query-format.js.map

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

@@ -33,7 +33,7 @@ exports.LinterQueryDefinition = {
 function addLintingRuleResult(ruleName, results, result) {
     const rule = linter_rules_1.LintingRules[ruleName];
     result.push(`   ╰ **${rule.info.name}** (${ruleName}):`);
-    for (const certainty of [linter_format_1.LintingCertainty.Definitely, linter_format_1.LintingCertainty.Maybe]) {
+    for (const certainty of [linter_format_1.LintingResultCertainty.Certain, linter_format_1.LintingResultCertainty.Uncertain]) {
         const certaintyResults = results.results.filter(r => r.certainty === certainty);
         if (certaintyResults.length) {
             result.push(`       ╰ ${certainty}:`);

package/queries/catalog/location-map-query/location-map-query-executor.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeLocationMapQuery = executeLocationMapQuery;
-const log_1 = require("../../../util/log");
+const parse_1 = require("../../../slicing/criterion/parse");
+const assert_1 = require("../../../util/assert");
 const fileIdRegex = /^(?<file>.*(\.[rR]))-/;
 function fuzzyFindFile(node, idMap) {
     if (node?.info.file) {
@@ -22,10 +23,11 @@ function fuzzyFindFile(node, idMap) {
     return '<inline>';
 }
 function executeLocationMapQuery({ ast, dataflow: { graph } }, queries) {
-    if (queries.length !== 1) {
-        log_1.log.warn('Id-Map query expects only up to one query, but got', queries.length);
-    }
     const start = Date.now();
+    const criteriaOfInterest = new Set(queries
+        .flatMap(q => q.ids ?? [])
+        .map(c => (0, parse_1.tryResolveSliceCriterionToId)(c, ast.idMap))
+        .filter(assert_1.isNotUndefined));
     const locationMap = {
         files: {},
         ids: {}
@@ -38,7 +40,7 @@ function executeLocationMapQuery({ ast, dataflow: { graph } }, queries) {
         count++;
     }
     for (const [id, node] of ast.idMap.entries()) {
-        if (node.location) {
+        if (node.location && (criteriaOfInterest.size === 0 || criteriaOfInterest.has(id))) {
             const file = fuzzyFindFile(node, ast.idMap);
             locationMap.ids[id] = [
                 inverseMap.get(file) ?? -1,

package/queries/catalog/location-map-query/location-map-query-format.d.ts

@@ -4,8 +4,11 @@ import { type OutputFormatter } from '../../../util/text/ansi';
 import Joi from 'joi';
 import type { NodeId } from '../../../r-bridge/lang-4.x/ast/model/processing/node-id';
 import type { SourceRange } from '../../../util/range';
+import type { SingleSlicingCriterion } from '../../../slicing/criterion/parse';
 export interface LocationMapQuery extends BaseQueryFormat {
     readonly type: 'location-map';
+    /** Optional list of ids to filter the results by. If not provided, all ids will be included. */
+    readonly ids?: readonly SingleSlicingCriterion[];
 }
 export type FileId = number & {
     readonly __fileId?: unique symbol;

package/queries/catalog/location-map-query/location-map-query-format.js

@@ -23,6 +23,7 @@ exports.LocationMapQueryDefinition = {
     },
     schema: joi_1.default.object({
         type: joi_1.default.string().valid('location-map').required().description('The type of the query.'),
+        ids: joi_1.default.array().items(joi_1.default.string()).optional().description('Optional list of ids to filter the results by.')
     }).description('The location map query retrieves the location of every id in the ast.'),
     flattenInvolvedNodes: () => []
 };

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

@@ -9,7 +9,7 @@ function executeSearch({ ast, dataflow, config }, queries) {
         const { search } = query;
         results.push({
             ids: (0, flowr_search_executor_1.runSearch)(search, { normalize: ast, dataflow, config })
-                .map(({ node }) => node.info.id),
+                .getElements().map(({ node }) => node.info.id),
             search
         });
     }

package/queries/catalog/static-slice-query/static-slice-query-executor.js

@@ -7,6 +7,7 @@ const reconstruct_1 = require("../../../reconstruct/reconstruct");
 const auto_select_defaults_1 = require("../../../reconstruct/auto-select/auto-select-defaults");
 const magic_comments_1 = require("../../../reconstruct/auto-select/magic-comments");
 const log_1 = require("../../../util/log");
+const _00_slice_1 = require("../../../core/steps/all/static-slicing/00-slice");
 function fingerPrintOfQuery(query) {
     return JSON.stringify(query);
 }
@@ -20,7 +21,7 @@ function executeStaticSliceQuery({ dataflow: { graph }, ast, config }, queries)
         }
         const { criteria, noReconstruction, noMagicComments } = query;
         const sliceStart = Date.now();
-        const slice = (0, static_slicer_1.staticSlicing)(graph, ast, criteria, config.solver.slicer?.threshold);
+        const slice = (0, static_slicer_1.staticSlice)(graph, ast, criteria, query.direction ?? _00_slice_1.SliceDirection.Backward, config.solver.slicer?.threshold);
         const sliceEnd = Date.now();
         if (noReconstruction) {
             results[key] = { slice: { ...slice, '.meta': { timing: sliceEnd - sliceStart } } };

package/queries/catalog/static-slice-query/static-slice-query-format.d.ts

@@ -4,6 +4,7 @@ import type { DEFAULT_DATAFLOW_PIPELINE, DEFAULT_SLICE_WITHOUT_RECONSTRUCT_PIPEL
 import type { SlicingCriteria } from '../../../slicing/criterion/parse';
 import Joi from 'joi';
 import { executeStaticSliceQuery } from './static-slice-query-executor';
+import { SliceDirection } from '../../../core/steps/all/static-slicing/00-slice';
 import type { NodeId } from '../../../r-bridge/lang-4.x/ast/model/processing/node-id';
 /** Calculates and returns all clusters encountered in the dataflow graph. */
 export interface StaticSliceQuery extends BaseQueryFormat {
@@ -14,6 +15,8 @@ export interface StaticSliceQuery extends BaseQueryFormat {
     readonly noReconstruction?: boolean;
     /** Should the magic comments (force-including lines within the slice) be ignored? */
     readonly noMagicComments?: boolean;
+    /** The direction to slice in. Defaults to backward slicing if unset. */
+    readonly direction?: SliceDirection;
 }
 export interface StaticSliceQueryResult extends BaseQueryResult {
     /**

package/queries/catalog/static-slice-query/static-slice-query-format.js

@@ -9,6 +9,7 @@ const time_1 = require("../../../util/text/time");
 const joi_1 = __importDefault(require("joi"));
 const static_slice_query_executor_1 = require("./static-slice-query-executor");
 const query_print_1 = require("../../query-print");
+const _00_slice_1 = require("../../../core/steps/all/static-slicing/00-slice");
 exports.StaticSliceQueryDefinition = {
     executor: static_slice_query_executor_1.executeStaticSliceQuery,
     asciiSummarizer: (formatter, _processed, queryResults, result) => {
@@ -37,7 +38,8 @@ exports.StaticSliceQueryDefinition = {
         type: joi_1.default.string().valid('static-slice').required().description('The type of the query.'),
         criteria: joi_1.default.array().items(joi_1.default.string()).min(0).required().description('The slicing criteria to use.'),
         noReconstruction: joi_1.default.boolean().optional().description('Do not reconstruct the slice into readable code.'),
-        noMagicComments: joi_1.default.boolean().optional().description('Should the magic comments (force-including lines within the slice) be ignored?')
+        noMagicComments: joi_1.default.boolean().optional().description('Should the magic comments (force-including lines within the slice) be ignored?'),
+        direction: joi_1.default.string().valid(...Object.values(_00_slice_1.SliceDirection)).optional().description('The direction to slice in. Defaults to backward slicing if unset.')
     }).description('Slice query used to slice the dataflow graph'),
     flattenInvolvedNodes: (queryResults) => {
         const flattened = [];

package/queries/query-print.d.ts

@@ -5,4 +5,4 @@ import type { DEFAULT_DATAFLOW_PIPELINE } from '../core/steps/pipeline/default-p
 import type { NodeId } from '../r-bridge/lang-4.x/ast/model/processing/node-id';
 export declare function asciiCallContext(formatter: OutputFormatter, results: QueryResults<'call-context'>['call-context'], processed: PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>): string;
 export declare function summarizeIdsIfTooLong(formatter: OutputFormatter, ids: readonly NodeId[]): string;
-export declare function asciiSummaryOfQueryResult(formatter: OutputFormatter, totalInMs: number, results: QueryResults<SupportedQueryTypes>, processed: PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>): string;
+export declare function asciiSummaryOfQueryResult<S extends SupportedQueryTypes>(formatter: OutputFormatter, totalInMs: number, results: Awaited<QueryResults<S>>, processed: PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>): string;

package/queries/query-print.js

@@ -81,7 +81,6 @@ function asciiSummaryOfQueryResult(formatter, totalInMs, results, processed) {
         }
         result.push(`Query: ${(0, ansi_1.bold)(query, formatter)}`);
         let timing = -1;
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
         for (const [key, value] of Object.entries(queryResults)) {
             if (key === '.meta') {
                 timing = value.timing;

package/queries/query.d.ts

@@ -24,11 +24,21 @@ import type { OriginQuery } from './catalog/origin-query/origin-query-format';
 import type { LinterQuery } from './catalog/linter-query/linter-query-format';
 import type { NodeId } from '../r-bridge/lang-4.x/ast/model/processing/node-id';
 import type { ControlFlowQuery } from './catalog/control-flow-query/control-flow-query-format';
-export type Query = CallContextQuery | ConfigQuery | SearchQuery | DataflowQuery | ControlFlowQuery | DataflowLensQuery | NormalizedAstQuery | IdMapQuery | DataflowClusterQuery | StaticSliceQuery | LineageQuery | DependenciesQuery | LocationMapQuery | HappensBeforeQuery | ResolveValueQuery | ProjectQuery | OriginQuery | LinterQuery;
+import type { DfShapeQuery } from './catalog/df-shape-query/df-shape-query-format';
+import type { AsyncOrSync, AsyncOrSyncType } from 'ts-essentials';
+/**
+ * These are all queries that can be executed from within flowR
+ * {@link SynchronousQuery} are queries that can be executed synchronously, i.e., they do not return a Promise.
+ */
+export type Query = CallContextQuery | ConfigQuery | SearchQuery | DataflowQuery | ControlFlowQuery | DataflowLensQuery | DfShapeQuery | NormalizedAstQuery | IdMapQuery | DataflowClusterQuery | StaticSliceQuery | LineageQuery | DependenciesQuery | LocationMapQuery | HappensBeforeQuery | ResolveValueQuery | ProjectQuery | OriginQuery | LinterQuery;
+export type SynchronousQuery = Exclude<Query, {
+    executor: (query: Query) => Promise<unknown>;
+}>;
+export type SupportedSynchronousQueryTypes = SynchronousQuery['type'];
 export type QueryArgumentsWithType<QueryType extends BaseQueryFormat['type']> = Query & {
     type: QueryType;
 };
-export type QueryExecutor<Query extends BaseQueryFormat, Result extends BaseQueryResult> = (data: BasicQueryData, query: readonly Query[]) => Result;
+export type QueryExecutor<Query extends BaseQueryFormat, Result extends BaseQueryResult> = (data: BasicQueryData, query: readonly Query[]) => AsyncOrSync<Result>;
 type SupportedQueries = {
     [QueryType in Query['type']]: SupportedQuery<QueryType>;
 };
@@ -232,6 +242,65 @@ export declare const SupportedQueries: {
         readonly schema: Joi.ObjectSchema<any>;
         readonly flattenInvolvedNodes: () => never[];
     };
+    readonly 'df-shape': {
+        readonly executor: typeof import("./catalog/df-shape-query/df-shape-query-executor").executeDfShapeQuery;
+        readonly asciiSummarizer: (formatter: OutputFormatter, _processed: PipelineOutput<import("../core/steps/pipeline/pipeline").Pipeline<{
+            readonly name: "parse";
+            readonly humanReadableName: "parse with R shell";
+            readonly description: "Parse the given R code into an AST";
+            readonly processor: (_results: unknown, input: Partial<import("../r-bridge/parser").ParseRequiredInput<string>>) => Promise<import("../r-bridge/parser").ParseStepOutput<string>>;
+            readonly executed: import("../core/steps/pipeline-step").PipelineStepStage.OncePerFile;
+            readonly printer: {
+                readonly 0: typeof import("../core/print/print").internalPrinter;
+                readonly 2: {
+                    (value: any, replacer?: (this: any, key: string, value: any) => any, space?: string | number): string;
+                    (value: any, replacer?: (number | string)[] | null, space?: string | number): string;
+                };
+                readonly 5: ({ parsed }: import("../r-bridge/parser").ParseStepOutput<string>, config: import("../util/quads").QuadSerializationConfiguration) => string;
+            };
+            readonly dependencies: readonly [];
+            readonly requiredInput: import("../r-bridge/parser").ParseRequiredInput<string>;
+        } | {
+            readonly name: "normalize";
+            readonly humanReadableName: "normalize";
+            readonly description: "Normalize the AST to flowR's AST";
+            readonly processor: (results: {
+                parse?: import("../r-bridge/parser").ParseStepOutput<string>;
+            }, input: Partial<import("../core/steps/all/core/10-normalize").NormalizeRequiredInput>) => import("../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst<import("../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../r-bridge/lang-4.x/ast/model/model").RNode<import("../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>>;
+            readonly executed: import("../core/steps/pipeline-step").PipelineStepStage.OncePerFile;
+            readonly printer: {
+                readonly 0: typeof import("../core/print/print").internalPrinter;
+                readonly 2: typeof import("../core/print/normalize-printer").normalizedAstToJson;
+                readonly 5: typeof import("../core/print/normalize-printer").normalizedAstToQuads;
+                readonly 3: typeof import("../core/print/normalize-printer").printNormalizedAstToMermaid;
+                readonly 4: typeof import("../core/print/normalize-printer").printNormalizedAstToMermaidUrl;
+            };
+            readonly dependencies: readonly ["parse"];
+            readonly requiredInput: import("../core/steps/all/core/10-normalize").NormalizeRequiredInput;
+        } | {
+            readonly humanReadableName: "dataflow";
+            readonly processor: (results: {
+                normalize?: import("../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
+            }, input: {
+                request?: import("../r-bridge/retriever").RParseRequests;
+                parser?: import("../r-bridge/parser").Parser<import("../r-bridge/parser").KnownParserType>;
+            }, config: import("../config").FlowrConfigOptions) => import("../dataflow/info").DataflowInformation;
+            readonly requiredInput: {};
+            readonly name: "dataflow";
+            readonly description: "Construct the dataflow graph";
+            readonly executed: import("../core/steps/pipeline-step").PipelineStepStage.OncePerFile;
+            readonly printer: {
+                readonly 0: typeof import("../core/print/print").internalPrinter;
+                readonly 2: typeof import("../core/print/dataflow-printer").dataflowGraphToJson;
+                readonly 5: typeof import("../core/print/dataflow-printer").dataflowGraphToQuads;
+                readonly 3: typeof import("../core/print/dataflow-printer").dataflowGraphToMermaid;
+                readonly 4: typeof import("../core/print/dataflow-printer").dataflowGraphToMermaidUrl;
+            };
+            readonly dependencies: readonly ["normalize"];
+        }>>, queryResults: BaseQueryResult, result: string[]) => true;
+        readonly schema: Joi.ObjectSchema<any>;
+        readonly flattenInvolvedNodes: () => never[];
+    };
     readonly 'id-map': {
         readonly executor: typeof import("./catalog/id-map-query/id-map-query-executor").executeIdMapQuery;
         readonly asciiSummarizer: (formatter: OutputFormatter, _processed: PipelineOutput<import("../core/steps/pipeline/pipeline").Pipeline<{
@@ -948,17 +1017,19 @@ export declare const SupportedQueries: {
     };
 };
 export type SupportedQueryTypes = keyof typeof SupportedQueries;
-export type QueryResult<Type extends Query['type']> = ReturnType<typeof SupportedQueries[Type]['executor']>;
-export declare function executeQueriesOfSameType<SpecificQuery extends Query>(data: BasicQueryData, ...queries: readonly SpecificQuery[]): QueryResult<SpecificQuery['type']>;
+export type QueryResult<Type extends Query['type']> = AsyncOrSync<ReturnType<typeof SupportedQueries[Type]['executor']>>;
+export declare function executeQueriesOfSameType<SpecificQuery extends SynchronousQuery>(data: BasicQueryData, queries: readonly SpecificQuery[]): AsyncOrSyncType<QueryResult<SpecificQuery['type']>>;
+export declare function executeQueriesOfSameType<SpecificQuery extends Query>(data: BasicQueryData, queries: readonly SpecificQuery[]): QueryResult<SpecificQuery['type']>;
 export type QueryResults<Base extends SupportedQueryTypes> = {
-    readonly [QueryType in Base]: QueryResult<QueryType>;
+    readonly [QueryType in Base]: Awaited<QueryResult<QueryType>>;
 } & BaseQueryResult;
 type OmitFromValues<T, K extends string | number | symbol> = {
     [P in keyof T]?: Omit<T[P], K>;
 };
 export type QueryResultsWithoutMeta<Queries extends Query> = OmitFromValues<Omit<QueryResults<Queries['type']>, '.meta'>, '.meta'>;
 export type Queries<Base extends SupportedQueryTypes, VirtualArguments extends VirtualCompoundConstraint<Base> = VirtualCompoundConstraint<Base>> = readonly (QueryArgumentsWithType<Base> | VirtualQueryArgumentsWithType<Base, VirtualArguments>)[];
-export declare function executeQueries<Base extends SupportedQueryTypes, VirtualArguments extends VirtualCompoundConstraint<Base> = VirtualCompoundConstraint<Base>>(data: BasicQueryData, queries: Queries<Base, VirtualArguments>): QueryResults<Base>;
+export declare function executeQueries<Base extends SupportedSynchronousQueryTypes, VirtualArguments extends VirtualCompoundConstraint<Base> = VirtualCompoundConstraint<Base>>(data: BasicQueryData, queries: Queries<Base, VirtualArguments>): QueryResults<Base>;
+export declare function executeQueries<Base extends SupportedQueryTypes, VirtualArguments extends VirtualCompoundConstraint<Base> = VirtualCompoundConstraint<Base>>(data: BasicQueryData, queries: Queries<Base, VirtualArguments>): AsyncOrSync<QueryResults<Base>>;
 export declare function SupportedQueriesSchema(): Joi.AlternativesSchema<any>;
 export declare const CompoundQuerySchema: Joi.ObjectSchema<any>;
 export declare function VirtualQuerySchema(): Joi.AlternativesSchema<any>;

package/queries/query.js

@@ -31,12 +31,14 @@ const project_query_format_1 = require("./catalog/project-query/project-query-fo
 const origin_query_format_1 = require("./catalog/origin-query/origin-query-format");
 const linter_query_format_1 = require("./catalog/linter-query/linter-query-format");
 const control_flow_query_format_1 = require("./catalog/control-flow-query/control-flow-query-format");
+const df_shape_query_format_1 = require("./catalog/df-shape-query/df-shape-query-format");
 exports.SupportedQueries = {
     'call-context': call_context_query_format_1.CallContextQueryDefinition,
     'config': config_query_format_1.ConfigQueryDefinition,
     'control-flow': control_flow_query_format_1.ControlFlowQueryDefinition,
     'dataflow': dataflow_query_format_1.DataflowQueryDefinition,
     'dataflow-lens': dataflow_lens_query_format_1.DataflowLensQueryDefinition,
+    'df-shape': df_shape_query_format_1.DfShapeQueryDefinition,
     'id-map': id_map_query_format_1.IdMapQueryDefinition,
     'normalized-ast': normalized_ast_query_format_1.NormalizedAstQueryDefinition,
     'dataflow-cluster': cluster_query_format_1.ClusterQueryDefinition,
@@ -51,7 +53,7 @@ exports.SupportedQueries = {
     'origin': origin_query_format_1.OriginQueryDefinition,
     'linter': linter_query_format_1.LinterQueryDefinition
 };
-function executeQueriesOfSameType(data, ...queries) {
+function executeQueriesOfSameType(data, queries) {
     (0, assert_1.guard)(queries.length > 0, 'At least one query must be provided');
     /* every query must have the same type */
     (0, assert_1.guard)(queries.every(q => q.type === queries[0].type), 'All queries must have the same type');
@@ -65,9 +67,7 @@ function isVirtualQuery(query) {
 function groupQueriesByType(queries) {
     const grouped = {};
     function addQuery(query) {
-        if (grouped[query.type] === undefined) {
-            grouped[query.type] = [];
-        }
+        grouped[query.type] ??= [];
         grouped[query.type].push(query);
     }
     for (const query of queries) {
@@ -84,17 +84,32 @@ function groupQueriesByType(queries) {
     }
     return grouped;
 }
+function isPromiseLike(value) {
+    return value !== null && typeof value === 'object' && typeof value.then === 'function';
+}
+/**
+ * This is the main query execution function that takes a set of queries and executes them on the given data.
+ */
 function executeQueries(data, queries) {
     const now = Date.now();
     const grouped = groupQueriesByType(queries);
-    const results = {};
-    for (const type of Object.keys(grouped)) {
-        results[type] = executeQueriesOfSameType(data, ...grouped[type]);
+    const entries = Object.entries(grouped);
+    const results = entries.map(([type, group]) => [type, executeQueriesOfSameType(data, group)]);
+    if (results.length === 0 || results.every(([_, r]) => !isPromiseLike(r))) {
+        // all results are synchronous, we can return them directly
+        const r = Object.fromEntries(results);
+        r['.meta'] = {
+            timing: Date.now() - now
+        };
+        return r;
     }
-    results['.meta'] = {
-        timing: Date.now() - now
-    };
-    return results;
+    return Promise.all(results.map(([type, result]) => Promise.resolve(result).then(resolvedResult => [type, resolvedResult]))).then(resultsArray => {
+        const results = Object.fromEntries(resultsArray);
+        results['.meta'] = {
+            timing: Date.now() - now
+        };
+        return results;
+    });
 }
 function SupportedQueriesSchema() {
     return joi_1.default.alternatives(Object.values(exports.SupportedQueries).map(q => q.schema)).description('Supported queries');

package/search/flowr-search-builder.d.ts

@@ -1,11 +1,11 @@
 import type { NodeId } from '../r-bridge/lang-4.x/ast/model/processing/node-id';
-import type { FlowrSearchElement, FlowrSearchElementFromQuery, FlowrSearchElements, FlowrSearchGetFilter } from './flowr-search';
+import type { FlowrSearchElement, FlowrSearchElements, FlowrSearchGetFilter } from './flowr-search';
 import type { FlowrFilter, FlowrFilterExpression } from './flowr-search-filters';
 import type { FlowrSearchGeneratorNode, GeneratorNames } from './search-executor/search-generators';
 import type { FlowrSearchTransformerNode, GetOutputOfTransformer, TransformerNames } from './search-executor/search-transformer';
 import type { SlicingCriteria } from '../slicing/criterion/parse';
 import type { ParentInformation } from '../r-bridge/lang-4.x/ast/model/processing/decorate';
-import type { Enrichment, EnrichmentArguments } from './search-executor/search-enrichers';
+import type { Enrichment, EnrichmentElementArguments } from './search-executor/search-enrichers';
 import type { MapperArguments } from './search-executor/search-mappers';
 import { Mapper } from './search-executor/search-mappers';
 import type { Query } from '../queries/query';
@@ -28,7 +28,7 @@ export declare const FlowrSearchGenerator: {
      * Internally, the {@link SupportedQuery#flattenInvolvedNodes} function is used to flatten the resulting nodes of the query.
      * Please note that, due to the fact that not every query involves dataflow nodes, the search may not contain any elements at all for certain queries.
      */
-    readonly fromQuery: (...from: readonly Query[]) => FlowrSearchBuilder<"from-query", [], ParentInformation, FlowrSearchElements<ParentInformation, FlowrSearchElementFromQuery<ParentInformation>[]>>;
+    readonly fromQuery: (...from: readonly Query[]) => FlowrSearchBuilder<"from-query", [], ParentInformation, FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>>;
     /**
      * Returns all elements (nodes/dataflow vertices) from the given data.
      */
@@ -86,7 +86,7 @@ export declare const Q: {
      * Internally, the {@link SupportedQuery#flattenInvolvedNodes} function is used to flatten the resulting nodes of the query.
      * Please note that, due to the fact that not every query involves dataflow nodes, the search may not contain any elements at all for certain queries.
      */
-    readonly fromQuery: (...from: readonly Query[]) => FlowrSearchBuilder<"from-query", [], ParentInformation, FlowrSearchElements<ParentInformation, FlowrSearchElementFromQuery<ParentInformation>[]>>;
+    readonly fromQuery: (...from: readonly Query[]) => FlowrSearchBuilder<"from-query", [], ParentInformation, FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>>;
     /**
      * Returns all elements (nodes/dataflow vertices) from the given data.
      */
@@ -188,7 +188,7 @@ export declare class FlowrSearchBuilder<Generator extends GeneratorNames, Transf
      * Adds the given enrichment to each element of the search.
      * Added enrichments can later be retrieved using the {@link enrichmentContent} function.
      */
-    with<ConcreteEnrichment extends Enrichment>(enrichment: ConcreteEnrichment, args?: EnrichmentArguments<ConcreteEnrichment>): FlowrSearchBuilderOut<Generator, Transformers, Info, 'with'>;
+    with<ConcreteEnrichment extends Enrichment>(enrichment: ConcreteEnrichment, args?: EnrichmentElementArguments<ConcreteEnrichment>): FlowrSearchBuilderOut<Generator, Transformers, Info, 'with'>;
     /**
      * Maps the elements of the search to new values using the given mapper function.
      */
@@ -196,7 +196,7 @@ export declare class FlowrSearchBuilder<Generator extends GeneratorNames, Transf
     /**
      * A convenience function that combines {@link with} and the {@link Mapper.Enrichment} mapper to immediately add an enrichment and then map to its value(s).
      */
-    get<ConcreteEnrichment extends Enrichment>(enrichment: ConcreteEnrichment, args?: EnrichmentArguments<ConcreteEnrichment>): FlowrSearchBuilderOut<Generator, Transformers, Info, 'with' | 'map'>;
+    get<ConcreteEnrichment extends Enrichment>(enrichment: ConcreteEnrichment, args?: EnrichmentElementArguments<ConcreteEnrichment>): FlowrSearchBuilderOut<Generator, Transformers, Info, 'with' | 'map'>;
     /**
      * merge combines the search results with those of another search.
      */