@eagleoutice/flowr 2.5.0 → 2.6.1

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.5.0",
+  "version": "2.6.1",
   "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",

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

@@ -0,0 +1,94 @@
+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';
+import { CfgKind } from '../cfg-kind';
+interface FlowrAnalyzerCacheOptions<Parser extends KnownParser> {
+    parser: Parser;
+    config: FlowrConfigOptions;
+    request: RParseRequests;
+    getId?: IdGenerator<NoInfo>;
+    overwriteFilePath?: string;
+}
+export 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 kind - The kind of CFG that is requested.
+     * @param simplifications - Simplification passes to be applied to the CFG.
+     */
+    controlflow(force: boolean | undefined, kind: CfgKind, simplifications: readonly CfgSimplificationPassName[] | undefined): Promise<ControlFlowInformation>;
+    /**
+     * Get the control flow graph (CFG) for the request if already available, otherwise return `undefined`.
+     * @param kind - The kind of CFG that is requested.
+     * @param simplifications - Simplification passes to be applied to the CFG.
+     *
+     * @see {@link FlowrAnalyzerCache#controlflow} - to get the control flow graph, computing if necessary.
+     */
+    peekControlflow(kind: CfgKind, simplifications: readonly CfgSimplificationPassName[] | undefined): ControlFlowInformation | undefined;
+}
+export {};

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

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowrAnalyzerCache = void 0;
+const flowr_cache_1 = require("./flowr-cache");
+const default_pipelines_1 = require("../../core/steps/pipeline/default-pipelines");
+const assert_1 = require("../../util/assert");
+const objectmap_1 = require("../../util/collections/objectmap");
+const extract_cfg_1 = require("../../control-flow/extract-cfg");
+const cfg_kind_1 = require("../cfg-kind");
+/**
+ * This provides the full analyzer caching layer, please avoid using this directly
+ * and prefer the {@link FlowrAnalyzer}.
+ */
+class FlowrAnalyzerCache extends flowr_cache_1.FlowrCache {
+    args;
+    pipeline = undefined;
+    controlFlowCache = undefined;
+    constructor(args) {
+        super();
+        this.args = args;
+        this.initCacheProviders();
+    }
+    initCacheProviders() {
+        this.pipeline = (0, default_pipelines_1.createDataflowPipeline)(this.args.parser, {
+            request: this.args.request,
+            getId: this.args.getId,
+            overwriteFilePath: this.args.overwriteFilePath
+        }, this.args.config);
+        this.controlFlowCache = {
+            simplified: new objectmap_1.ObjectMap(),
+        };
+    }
+    static create(data) {
+        return new FlowrAnalyzerCache(data);
+    }
+    receive(event) {
+        super.receive(event);
+        switch (event.type) {
+            case "full" /* CacheInvalidationEventType.Full */:
+                this.initCacheProviders();
+                break;
+            default:
+                (0, assert_1.assertUnreachable)(event.type);
+        }
+    }
+    get() {
+        /* this will do a ref assignment, so indirect force */
+        return this.computeIfAbsent(false, () => this.pipeline.getResults(true));
+    }
+    reset() {
+        this.receive({ type: "full" /* CacheInvalidationEventType.Full */ });
+    }
+    async runTapeUntil(force, until) {
+        (0, assert_1.guard)(this.args.request && (Array.isArray(this.args.request) ? this.args.request.length > 0 : true), 'At least one request must be set to run the analysis pipeline');
+        if (force) {
+            this.reset();
+        }
+        let g;
+        while ((g = until()) === undefined && this.pipeline.hasNextStep()) {
+            await this.pipeline.nextStep();
+        }
+        (0, assert_1.guard)(g !== undefined, 'Could not reach the desired pipeline step, invalid cache state(?)');
+        return g;
+    }
+    /**
+     * 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.
+     */
+    async parse(force) {
+        const d = this.get();
+        return this.runTapeUntil(force, () => d.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() {
+        return this.get().parse;
+    }
+    /**
+     * 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.
+     */
+    async normalize(force) {
+        const d = this.get();
+        return this.runTapeUntil(force, () => d.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() {
+        return this.get().normalize;
+    }
+    /**
+     * 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.
+     */
+    async dataflow(force) {
+        const d = this.get();
+        return this.runTapeUntil(force, () => d.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() {
+        return this.get().dataflow;
+    }
+    /**
+     * Get the control flow graph (CFG) for the request, computing if necessary.
+     * @param force - Do not use the cache, instead force new analyses.
+     * @param kind - The kind of CFG that is requested.
+     * @param simplifications - Simplification passes to be applied to the CFG.
+     */
+    async controlflow(force, kind, simplifications) {
+        (0, assert_1.guard)(kind === cfg_kind_1.CfgKind.Quick ? simplifications === undefined : true, 'Cannot apply simplifications to quick CFG');
+        simplifications ??= [];
+        if (!force) {
+            const value = this.controlFlowCache.simplified.get([simplifications, kind]);
+            if (value !== undefined) {
+                return value;
+            }
+        }
+        const normalized = await this.normalize(force);
+        let result;
+        switch (kind) {
+            case cfg_kind_1.CfgKind.WithDataflow:
+                result = (0, extract_cfg_1.extractCfg)(normalized, this.args.config, (await this.dataflow()).graph, simplifications);
+                break;
+            case cfg_kind_1.CfgKind.NoDataflow:
+                result = (0, extract_cfg_1.extractCfg)(normalized, this.args.config, undefined, simplifications);
+                break;
+            case cfg_kind_1.CfgKind.Quick:
+                result = this.peekDataflow()?.cfgQuick ?? (0, extract_cfg_1.extractCfgQuick)(normalized);
+                break;
+        }
+        this.controlFlowCache.simplified.set([simplifications, kind], result);
+        return result;
+    }
+    /**
+     * Get the control flow graph (CFG) for the request if already available, otherwise return `undefined`.
+     * @param kind - The kind of CFG that is requested.
+     * @param simplifications - Simplification passes to be applied to the CFG.
+     *
+     * @see {@link FlowrAnalyzerCache#controlflow} - to get the control flow graph, computing if necessary.
+     */
+    peekControlflow(kind, simplifications) {
+        return this.controlFlowCache.simplified.get([simplifications ?? [], kind]);
+    }
+}
+exports.FlowrAnalyzerCache = FlowrAnalyzerCache;
+//# sourceMappingURL=flowr-analyzer-cache.js.map

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

@@ -0,0 +1,28 @@
+export declare const enum CacheInvalidationEventType {
+    Full = "full"
+}
+export type CacheInvalidationEvent = {
+    type: CacheInvalidationEventType.Full;
+};
+export interface CacheInvalidationEventReceiver {
+    receive(event: CacheInvalidationEvent): void;
+}
+/**
+ * Central class for caching analysis results in FlowR.
+ */
+export declare abstract class FlowrCache<Cache> implements CacheInvalidationEventReceiver {
+    private value;
+    private dependents;
+    registerDependent(dependent: CacheInvalidationEventReceiver): void;
+    removeDependent(dependent: CacheInvalidationEventReceiver): void;
+    receive(event: CacheInvalidationEvent): void;
+    /**
+     * Notify all dependents of a cache invalidation event.
+     */
+    notifyDependents(event: CacheInvalidationEvent): void;
+    /**
+     * Get the cached value or compute it if not present.
+     * This will, by default, not trigger any {@link notifyDependents} calls, as this is only a cache retrieval.
+     */
+    protected computeIfAbsent(force: boolean | undefined, compute: () => Cache): Cache;
+}

package/project/cache/flowr-cache.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowrCache = void 0;
+const assert_1 = require("../../util/assert");
+/**
+ * Central class for caching analysis results in FlowR.
+ */
+class FlowrCache {
+    value = undefined;
+    dependents = [];
+    registerDependent(dependent) {
+        this.dependents.push(dependent);
+    }
+    removeDependent(dependent) {
+        this.dependents = this.dependents.filter(d => d !== dependent);
+    }
+    receive(event) {
+        /* we will update this as soon as we support incremental update patterns */
+        switch (event.type) {
+            case "full" /* CacheInvalidationEventType.Full */:
+                this.value = undefined;
+                break;
+            default:
+                (0, assert_1.assertUnreachable)(event.type);
+        }
+        /* in the future we want to defer this *after* the dataflow is re-computed, then all receivers can decide whether they need to update */
+        this.notifyDependents(event);
+    }
+    /**
+     * Notify all dependents of a cache invalidation event.
+     */
+    notifyDependents(event) {
+        for (const dependent of this.dependents) {
+            dependent.receive(event);
+        }
+    }
+    /**
+     * Get the cached value or compute it if not present.
+     * This will, by default, not trigger any {@link notifyDependents} calls, as this is only a cache retrieval.
+     */
+    computeIfAbsent(force, compute) {
+        if (this.value === undefined || force) {
+            this.value = compute();
+        }
+        return this.value;
+    }
+}
+exports.FlowrCache = FlowrCache;
+//# sourceMappingURL=flowr-cache.js.map

package/project/cfg-kind.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Denotes the kind of control flow graph (CFG).
+ */
+export declare enum CfgKind {
+    /**
+     * CFG with dataflow information.
+     */
+    WithDataflow = 0,
+    /**
+     * CFG without dataflow information.
+     */
+    NoDataflow = 1,
+    /**
+     * A CFG version that is much quicker and does not apply any simplifications or dataflow information.
+     */
+    Quick = 2
+}

package/project/cfg-kind.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CfgKind = void 0;
+/**
+ * Denotes the kind of control flow graph (CFG).
+ */
+var CfgKind;
+(function (CfgKind) {
+    /**
+     * CFG with dataflow information.
+     */
+    CfgKind[CfgKind["WithDataflow"] = 0] = "WithDataflow";
+    /**
+     * CFG without dataflow information.
+     */
+    CfgKind[CfgKind["NoDataflow"] = 1] = "NoDataflow";
+    /**
+     * A CFG version that is much quicker and does not apply any simplifications or dataflow information.
+     */
+    CfgKind[CfgKind["Quick"] = 2] = "Quick";
+})(CfgKind || (exports.CfgKind = CfgKind = {}));
+//# sourceMappingURL=cfg-kind.js.map

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

@@ -0,0 +1,39 @@
+import type { FlowrAnalyzerPlugin } from '../plugins/flowr-analyzer-plugin';
+import type { FlowrAnalyzerContext } from './flowr-analyzer-context';
+/**
+ * Abstract class representing the context, a context may be modified and enriched by plugins (see {@link FlowrAnalyzerPlugin}).
+ *
+ * Please use the specialized contexts like {@link FlowrAnalyzerFilesContext} or {@link FlowrAnalyzerLoadingOrderContext} to work with flowR and
+ * in general, use the {@link FlowrAnalyzerContext} to access the full project context.
+ */
+export declare abstract class AbstractFlowrAnalyzerContext<In, Out, Plugin extends FlowrAnalyzerPlugin<In, Out>> {
+    /**
+     * A human-readable name of the context. Try to make it unique to avoid confusion in the logs.
+     */
+    abstract readonly name: string;
+    /**
+     * The plugins registered for this context. These build the foundation for {@link applyPlugins}.
+     */
+    protected readonly plugins: readonly Plugin[];
+    /**
+     * The linked full project context, allowing plugins to modify and access it.
+     */
+    protected readonly ctx: FlowrAnalyzerContext;
+    /**
+     * Creates a new context with the given project context, a default plugin (to be used when no other is registered)
+     */
+    protected constructor(ctx: FlowrAnalyzerContext, defaultPlugin: Plugin, plugins?: readonly Plugin[]);
+    /**
+     * Run all registered plugins on the given args, please be aware that if they are async, it is up to you to
+     * await them.
+     */
+    protected applyPlugins(args: Parameters<Plugin['processor']>[1]): Out[];
+    /**
+     * Returns the project context this sub-context is attached to
+     */
+    getAttachedContext(): FlowrAnalyzerContext;
+    /**
+     * Reset the context to its initial state.
+     */
+    abstract reset(): void;
+}

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

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractFlowrAnalyzerContext = void 0;
+const assert_1 = require("../../util/assert");
+/**
+ * Abstract class representing the context, a context may be modified and enriched by plugins (see {@link FlowrAnalyzerPlugin}).
+ *
+ * Please use the specialized contexts like {@link FlowrAnalyzerFilesContext} or {@link FlowrAnalyzerLoadingOrderContext} to work with flowR and
+ * in general, use the {@link FlowrAnalyzerContext} to access the full project context.
+ */
+class AbstractFlowrAnalyzerContext {
+    /**
+     * The plugins registered for this context. These build the foundation for {@link applyPlugins}.
+     */
+    plugins;
+    /**
+     * The linked full project context, allowing plugins to modify and access it.
+     */
+    ctx;
+    /**
+     * Creates a new context with the given project context, a default plugin (to be used when no other is registered)
+     */
+    constructor(ctx, defaultPlugin, plugins) {
+        this.plugins = [...plugins ?? [], defaultPlugin];
+        this.ctx = ctx;
+    }
+    /**
+     * Run all registered plugins on the given args, please be aware that if they are async, it is up to you to
+     * await them.
+     */
+    applyPlugins(args) {
+        const res = [];
+        for (const plugin of this.plugins) {
+            res.push(plugin.processor(this.ctx, args));
+        }
+        return res.filter(assert_1.isNotUndefined);
+    }
+    /**
+     * Returns the project context this sub-context is attached to
+     */
+    getAttachedContext() {
+        return this.ctx;
+    }
+}
+exports.AbstractFlowrAnalyzerContext = AbstractFlowrAnalyzerContext;
+//# sourceMappingURL=abstract-flowr-analyzer-context.js.map