@eagleoutice/flowr 2.2.1 → 2.2.3

package/core/steps/pipeline/default-pipelines.d.ts

@@ -1,9 +1,11 @@
 /**
- * Contains the default pipeline for working with flowr
+ * Contains the default pipeline for working with flowR
  */
 import type { PipelineInput } from './pipeline';
 import type { KnownParser, Parser } from '../../../r-bridge/parser';
 import { PipelineExecutor } from '../../pipeline-executor';
+import type { RShell } from '../../../r-bridge/shell';
+import type { TreeSitterExecutor } from '../../../r-bridge/lang-4.x/tree-sitter/tree-sitter-executor';
 export declare const DEFAULT_SLICING_PIPELINE: import("./pipeline").Pipeline<{
     readonly name: "parse";
     readonly humanReadableName: "parse with R shell";
@@ -256,21 +258,6 @@ export declare const TREE_SITTER_SLICING_PIPELINE: import("./pipeline").Pipeline
         readonly 4: typeof import("../../print/dataflow-printer").dataflowGraphToMermaidUrl;
     };
     readonly dependencies: readonly ["normalize"];
-} | {
-    readonly name: "parse";
-    readonly humanReadableName: "parse with tree-sitter";
-    readonly description: "Parse the given R code into an AST using tree-sitter";
-    readonly processor: (_results: unknown, input: Partial<import("../../../r-bridge/parser").ParseRequiredInput<import("web-tree-sitter").Tree>>) => Promise<import("../../../r-bridge/parser").ParseStepOutput<import("web-tree-sitter").Tree>>;
-    readonly executed: import("../pipeline-step").PipelineStepStage.OncePerFile;
-    readonly printer: {
-        readonly 0: typeof import("../../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 dependencies: readonly [];
-    readonly requiredInput: import("../../../r-bridge/parser").ParseRequiredInput<import("web-tree-sitter").Tree>;
 } | {
     readonly name: "slice";
     readonly humanReadableName: "static slice";
@@ -299,6 +286,21 @@ export declare const TREE_SITTER_SLICING_PIPELINE: import("./pipeline").Pipeline
     };
     readonly dependencies: readonly ["slice"];
     readonly requiredInput: import("../all/static-slicing/10-reconstruct").ReconstructRequiredInput;
+} | {
+    readonly name: "parse";
+    readonly humanReadableName: "parse with tree-sitter";
+    readonly description: "Parse the given R code into an AST using tree-sitter";
+    readonly processor: (_results: unknown, input: Partial<import("../../../r-bridge/parser").ParseRequiredInput<import("web-tree-sitter").Tree>>) => Promise<import("../../../r-bridge/parser").ParseStepOutput<import("web-tree-sitter").Tree>>;
+    readonly executed: import("../pipeline-step").PipelineStepStage.OncePerFile;
+    readonly printer: {
+        readonly 0: typeof import("../../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 dependencies: readonly [];
+    readonly requiredInput: import("../../../r-bridge/parser").ParseRequiredInput<import("web-tree-sitter").Tree>;
 } | {
     readonly name: "normalize";
     readonly humanReadableName: "normalize tree-sitter tree";
@@ -337,21 +339,6 @@ export declare const TREE_SITTER_SLICE_AND_RECONSTRUCT_PIPELINE: import("./pipel
         readonly 4: typeof import("../../print/dataflow-printer").dataflowGraphToMermaidUrl;
     };
     readonly dependencies: readonly ["normalize"];
-} | {
-    readonly name: "parse";
-    readonly humanReadableName: "parse with tree-sitter";
-    readonly description: "Parse the given R code into an AST using tree-sitter";
-    readonly processor: (_results: unknown, input: Partial<import("../../../r-bridge/parser").ParseRequiredInput<import("web-tree-sitter").Tree>>) => Promise<import("../../../r-bridge/parser").ParseStepOutput<import("web-tree-sitter").Tree>>;
-    readonly executed: import("../pipeline-step").PipelineStepStage.OncePerFile;
-    readonly printer: {
-        readonly 0: typeof import("../../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 dependencies: readonly [];
-    readonly requiredInput: import("../../../r-bridge/parser").ParseRequiredInput<import("web-tree-sitter").Tree>;
 } | {
     readonly name: "slice";
     readonly humanReadableName: "static slice";
@@ -380,6 +367,21 @@ export declare const TREE_SITTER_SLICE_AND_RECONSTRUCT_PIPELINE: import("./pipel
     };
     readonly dependencies: readonly ["slice"];
     readonly requiredInput: import("../all/static-slicing/10-reconstruct").ReconstructRequiredInput;
+} | {
+    readonly name: "parse";
+    readonly humanReadableName: "parse with tree-sitter";
+    readonly description: "Parse the given R code into an AST using tree-sitter";
+    readonly processor: (_results: unknown, input: Partial<import("../../../r-bridge/parser").ParseRequiredInput<import("web-tree-sitter").Tree>>) => Promise<import("../../../r-bridge/parser").ParseStepOutput<import("web-tree-sitter").Tree>>;
+    readonly executed: import("../pipeline-step").PipelineStepStage.OncePerFile;
+    readonly printer: {
+        readonly 0: typeof import("../../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 dependencies: readonly [];
+    readonly requiredInput: import("../../../r-bridge/parser").ParseRequiredInput<import("web-tree-sitter").Tree>;
 } | {
     readonly name: "normalize";
     readonly humanReadableName: "normalize tree-sitter tree";
@@ -418,6 +420,20 @@ export declare const TREE_SITTER_SLICE_WITHOUT_RECONSTRUCT_PIPELINE: import("./p
         readonly 4: typeof import("../../print/dataflow-printer").dataflowGraphToMermaidUrl;
     };
     readonly dependencies: readonly ["normalize"];
+} | {
+    readonly name: "slice";
+    readonly humanReadableName: "static slice";
+    readonly description: "Calculate the actual static slice from the dataflow graph and the given slicing criteria";
+    readonly processor: (results: {
+        dataflow?: import("../../../dataflow/info").DataflowInformation;
+        normalize?: import("../../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
+    }, input: Partial<import("../all/static-slicing/00-slice").SliceRequiredInput>) => Readonly<import("../../../slicing/static/slicer-types").SliceResult>;
+    readonly executed: import("../pipeline-step").PipelineStepStage.OncePerRequest;
+    readonly printer: {
+        readonly 0: typeof import("../../print/print").internalPrinter;
+    };
+    readonly dependencies: readonly ["dataflow"];
+    readonly requiredInput: import("../all/static-slicing/00-slice").SliceRequiredInput;
 } | {
     readonly name: "parse";
     readonly humanReadableName: "parse with tree-sitter";
@@ -433,20 +449,6 @@ export declare const TREE_SITTER_SLICE_WITHOUT_RECONSTRUCT_PIPELINE: import("./p
     };
     readonly dependencies: readonly [];
     readonly requiredInput: import("../../../r-bridge/parser").ParseRequiredInput<import("web-tree-sitter").Tree>;
-} | {
-    readonly name: "slice";
-    readonly humanReadableName: "static slice";
-    readonly description: "Calculate the actual static slice from the dataflow graph and the given slicing criteria";
-    readonly processor: (results: {
-        dataflow?: import("../../../dataflow/info").DataflowInformation;
-        normalize?: import("../../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
-    }, input: Partial<import("../all/static-slicing/00-slice").SliceRequiredInput>) => Readonly<import("../../../slicing/static/slicer-types").SliceResult>;
-    readonly executed: import("../pipeline-step").PipelineStepStage.OncePerRequest;
-    readonly printer: {
-        readonly 0: typeof import("../../print/print").internalPrinter;
-    };
-    readonly dependencies: readonly ["dataflow"];
-    readonly requiredInput: import("../all/static-slicing/00-slice").SliceRequiredInput;
 } | {
     readonly name: "normalize";
     readonly humanReadableName: "normalize tree-sitter tree";
@@ -466,8 +468,8 @@ export declare const TREE_SITTER_SLICE_WITHOUT_RECONSTRUCT_PIPELINE: import("./p
     readonly requiredInput: import("../all/core/10-normalize").NormalizeRequiredInput;
 }>;
 /**
- * The default pipeline for working with flowr, including the dataflow step,
- * see the {@link DEFAULT_NORMALIZE_PIPELINE} for the pipeline without the dataflow step,
+ * The default pipeline for working with flowR, including the dataflow step.
+ * See the {@link DEFAULT_NORMALIZE_PIPELINE} for the pipeline without the dataflow step
  * and the {@link DEFAULT_SLICE_AND_RECONSTRUCT_PIPELINE} for the pipeline with slicing and reconstructing steps
  */
 export declare const DEFAULT_DATAFLOW_PIPELINE: import("./pipeline").Pipeline<{
@@ -678,7 +680,15 @@ export declare const TREE_SITTER_PARSE_PIPELINE: import("./pipeline").Pipeline<{
     readonly dependencies: readonly [];
     readonly requiredInput: import("../../../r-bridge/parser").ParseRequiredInput<import("web-tree-sitter").Tree>;
 }>;
+export declare function createParsePipeline(parser: TreeSitterExecutor, inputs: Omit<PipelineInput<typeof DEFAULT_PARSE_PIPELINE>, 'parser'>): PipelineExecutor<typeof TREE_SITTER_PARSE_PIPELINE>;
+export declare function createParsePipeline(parser: RShell, inputs: Omit<PipelineInput<typeof DEFAULT_PARSE_PIPELINE>, 'parser'>): PipelineExecutor<typeof DEFAULT_PARSE_PIPELINE>;
 export declare function createParsePipeline(parser: KnownParser, inputs: Omit<PipelineInput<typeof DEFAULT_PARSE_PIPELINE>, 'parser'>): PipelineExecutor<typeof DEFAULT_PARSE_PIPELINE> | PipelineExecutor<typeof TREE_SITTER_PARSE_PIPELINE>;
+export declare function createSlicePipeline(parser: TreeSitterExecutor, inputs: Omit<PipelineInput<typeof DEFAULT_SLICING_PIPELINE>, 'parser'>): PipelineExecutor<typeof TREE_SITTER_SLICING_PIPELINE>;
+export declare function createSlicePipeline(parser: RShell, inputs: Omit<PipelineInput<typeof DEFAULT_SLICING_PIPELINE>, 'parser'>): PipelineExecutor<typeof DEFAULT_SLICING_PIPELINE>;
 export declare function createSlicePipeline(parser: KnownParser, inputs: Omit<PipelineInput<typeof DEFAULT_SLICING_PIPELINE>, 'parser'>): PipelineExecutor<typeof DEFAULT_SLICING_PIPELINE> | PipelineExecutor<typeof TREE_SITTER_SLICING_PIPELINE>;
+export declare function createNormalizePipeline(parser: TreeSitterExecutor, inputs: Omit<PipelineInput<typeof DEFAULT_NORMALIZE_PIPELINE>, 'parser'>): PipelineExecutor<typeof TREE_SITTER_NORMALIZE_PIPELINE>;
+export declare function createNormalizePipeline(parser: RShell, inputs: Omit<PipelineInput<typeof DEFAULT_NORMALIZE_PIPELINE>, 'parser'>): PipelineExecutor<typeof DEFAULT_NORMALIZE_PIPELINE>;
 export declare function createNormalizePipeline(parser: KnownParser, inputs: Omit<PipelineInput<typeof DEFAULT_NORMALIZE_PIPELINE>, 'parser'>): PipelineExecutor<typeof DEFAULT_NORMALIZE_PIPELINE> | PipelineExecutor<typeof TREE_SITTER_NORMALIZE_PIPELINE>;
+export declare function createDataflowPipeline(parser: TreeSitterExecutor, inputs: Omit<PipelineInput<typeof DEFAULT_DATAFLOW_PIPELINE>, 'parser'>): PipelineExecutor<typeof TREE_SITTER_DATAFLOW_PIPELINE>;
+export declare function createDataflowPipeline(parser: RShell, inputs: Omit<PipelineInput<typeof DEFAULT_DATAFLOW_PIPELINE>, 'parser'>): PipelineExecutor<typeof DEFAULT_DATAFLOW_PIPELINE>;
 export declare function createDataflowPipeline(parser: KnownParser, inputs: Omit<PipelineInput<typeof DEFAULT_DATAFLOW_PIPELINE>, 'parser'>): PipelineExecutor<typeof DEFAULT_DATAFLOW_PIPELINE> | PipelineExecutor<typeof TREE_SITTER_DATAFLOW_PIPELINE>;

package/core/steps/pipeline/default-pipelines.js

@@ -21,8 +21,8 @@ exports.TREE_SITTER_SLICING_PIPELINE = (0, pipeline_1.createPipeline)(_01_parse_
 exports.TREE_SITTER_SLICE_AND_RECONSTRUCT_PIPELINE = exports.TREE_SITTER_SLICING_PIPELINE;
 exports.TREE_SITTER_SLICE_WITHOUT_RECONSTRUCT_PIPELINE = (0, pipeline_1.createPipeline)(_01_parse_tree_sitter_1.PARSE_WITH_TREE_SITTER_STEP, _11_normalize_tree_sitter_1.NORMALIZE_TREE_SITTER, _20_dataflow_1.STATIC_DATAFLOW, _00_slice_1.STATIC_SLICE);
 /**
- * The default pipeline for working with flowr, including the dataflow step,
- * see the {@link DEFAULT_NORMALIZE_PIPELINE} for the pipeline without the dataflow step,
+ * The default pipeline for working with flowR, including the dataflow step.
+ * See the {@link DEFAULT_NORMALIZE_PIPELINE} for the pipeline without the dataflow step
  * and the {@link DEFAULT_SLICE_AND_RECONSTRUCT_PIPELINE} for the pipeline with slicing and reconstructing steps
  */
 exports.DEFAULT_DATAFLOW_PIPELINE = (0, pipeline_1.createPipeline)(_00_parse_1.PARSE_WITH_R_SHELL_STEP, _10_normalize_1.NORMALIZE, _20_dataflow_1.STATIC_DATAFLOW);
@@ -32,6 +32,11 @@ exports.DEFAULT_NORMALIZE_PIPELINE = (0, pipeline_1.createPipeline)(_00_parse_1.
 exports.TREE_SITTER_NORMALIZE_PIPELINE = (0, pipeline_1.createPipeline)(_01_parse_tree_sitter_1.PARSE_WITH_TREE_SITTER_STEP, _11_normalize_tree_sitter_1.NORMALIZE_TREE_SITTER);
 exports.DEFAULT_PARSE_PIPELINE = (0, pipeline_1.createPipeline)(_00_parse_1.PARSE_WITH_R_SHELL_STEP);
 exports.TREE_SITTER_PARSE_PIPELINE = (0, pipeline_1.createPipeline)(_01_parse_tree_sitter_1.PARSE_WITH_TREE_SITTER_STEP);
+/**
+ * Returns either a {@link DEFAULT_PARSE_PIPELINE} or a {@link TREE_SITTER_PARSE_PIPELINE} depending on the parser used.
+ *
+ * @see {@link createNormalizePipeline}, {@link createDataflowPipeline}, {@link createSlicePipeline}
+ */
 function createParsePipeline(parser, inputs) {
     const base = parser.name === 'tree-sitter' ? exports.TREE_SITTER_PARSE_PIPELINE : exports.DEFAULT_PARSE_PIPELINE;
     return new pipeline_executor_1.PipelineExecutor(base, {
@@ -39,6 +44,11 @@ function createParsePipeline(parser, inputs) {
         ...inputs
     });
 }
+/**
+ * Returns either a {@link DEFAULT_SLICING_PIPELINE} or a {@link TREE_SITTER_SLICING_PIPELINE} depending on the parser used.
+ *
+ * @see {@link createParsePipeline}, {@link createNormalizePipeline}, {@link createDataflowPipeline}
+ */
 function createSlicePipeline(parser, inputs) {
     const base = parser.name === 'tree-sitter' ? exports.TREE_SITTER_SLICING_PIPELINE : exports.DEFAULT_SLICING_PIPELINE;
     return new pipeline_executor_1.PipelineExecutor(base, {
@@ -46,6 +56,11 @@ function createSlicePipeline(parser, inputs) {
         ...inputs
     });
 }
+/**
+ * Returns either a {@link DEFAULT_NORMALIZE_PIPELINE} or a {@link TREE_SITTER_NORMALIZE_PIPELINE} depending on the parser used.
+ *
+ * @see {@link createParsePipeline}, {@link createDataflowPipeline}, {@link createSlicePipeline}
+ */
 function createNormalizePipeline(parser, inputs) {
     const base = parser.name === 'tree-sitter' ? exports.TREE_SITTER_NORMALIZE_PIPELINE : exports.DEFAULT_NORMALIZE_PIPELINE;
     return new pipeline_executor_1.PipelineExecutor(base, {
@@ -53,6 +68,12 @@ function createNormalizePipeline(parser, inputs) {
         ...inputs
     });
 }
+/**
+ * Returns either a {@link DEFAULT_DATAFLOW_PIPELINE} or a {@link TREE_SITTER_DATAFLOW_PIPELINE} depending on the parser used.
+ *
+ * @see {@link createParsePipeline}, {@link createNormalizePipeline}, {@link createSlicePipeline}
+ *
+ */
 function createDataflowPipeline(parser, inputs) {
     const base = parser.name === 'tree-sitter' ? exports.TREE_SITTER_DATAFLOW_PIPELINE : exports.DEFAULT_DATAFLOW_PIPELINE;
     return new pipeline_executor_1.PipelineExecutor(base, {

package/core/steps/pipeline/pipeline.d.ts

@@ -120,7 +120,7 @@ export type PipelineOutput<P extends Pipeline> = {
  *
  * 0) the collection of {@link IPipelineStep|steps} is not empty
  * 1) all {@link IPipelineStepOrder#name|names} of {@link IPipelineStep|steps} are unique for the given pipeline
- * 2) all {@link IPipelineStepOrder#dependencies|dependencies} of all {@link IPipelineStep|steps} are exist
+ * 2) all {@link IPipelineStepOrder#dependencies|dependencies} of all {@link IPipelineStep|steps} exist
  * 3) there are no cycles in the dependency graph
  * 4) the target of a {@link IPipelineStepOrder#decorates|step's decoration} exists
  * 5) if a {@link IPipelineStepOrder#decorates|decoration} applies, all of its {@link IPipelineStepOrder#dependencies|dependencies} are already in the pipeline

package/core/steps/pipeline/pipeline.js

@@ -9,7 +9,7 @@ const create_pipeline_1 = require("./create-pipeline");
  *
  * 0) the collection of {@link IPipelineStep|steps} is not empty
  * 1) all {@link IPipelineStepOrder#name|names} of {@link IPipelineStep|steps} are unique for the given pipeline
- * 2) all {@link IPipelineStepOrder#dependencies|dependencies} of all {@link IPipelineStep|steps} are exist
+ * 2) all {@link IPipelineStepOrder#dependencies|dependencies} of all {@link IPipelineStep|steps} exist
  * 3) there are no cycles in the dependency graph
  * 4) the target of a {@link IPipelineStepOrder#decorates|step's decoration} exists
  * 5) if a {@link IPipelineStepOrder#decorates|decoration} applies, all of its {@link IPipelineStepOrder#dependencies|dependencies} are already in the pipeline

package/core/steps/pipeline-step.d.ts

@@ -67,9 +67,7 @@ export interface IPipelineStep<Name extends PipelineStepName = PipelineStepName,
     readonly description: string;
     /** The main processor that essentially performs the logic of this step */
     readonly processor: (...input: Parameters<Fn>) => ReturnType<Fn>;
-    /**
-     * How to visualize the results of the respective step to the user?
-     */
+    /** How to visualize the results of the respective step to the user? */
     readonly printer: {
         [K in StepOutputFormat]?: IPipelineStepPrinter<Fn, K, never[]>;
     } & {

package/dataflow/environments/resolve-by-name.d.ts

@@ -4,6 +4,7 @@ import type { Identifier, IdentifierDefinition } from './identifier';
 import { ReferenceType } from './identifier';
 import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
 import type { DataflowGraph } from '../graph/graph';
+import type { AstIdMap } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
 /**
  * Resolves a given identifier name to a list of its possible definition location using R scoping and resolving rules.
  *
@@ -18,9 +19,9 @@ export declare function resolveByName(name: Identifier, environment: REnvironmen
 export declare function resolvesToBuiltInConstant(name: Identifier | undefined, environment: REnvironmentInformation, wantedValue: unknown): Ternary;
 export declare function resolveToConstants(name: Identifier | undefined, environment: REnvironmentInformation): unknown[] | undefined;
 export declare function getAliases(sourceIds: readonly NodeId[], dataflow: DataflowGraph, environment: REnvironmentInformation): NodeId[] | undefined;
-export declare function resolveToValues(identifier: Identifier | undefined, environment: REnvironmentInformation, graph: DataflowGraph): unknown[] | undefined;
+export declare function resolveToValues(identifier: Identifier | undefined, environment: REnvironmentInformation, idMap?: AstIdMap): unknown[] | undefined;
 /**
  * Convenience function using the variable resolver as specified within the configuration file
  * In the future we may want to have this set once at the start of the analysis
  */
-export declare function resolveValueOfVariable(identifier: Identifier | undefined, environment: REnvironmentInformation, graph: DataflowGraph): unknown[] | undefined;
+export declare function resolveValueOfVariable(identifier: Identifier | undefined, environment: REnvironmentInformation, idMap?: AstIdMap): unknown[] | undefined;

package/dataflow/environments/resolve-by-name.js

@@ -147,7 +147,7 @@ function getAliases(sourceIds, dataflow, environment) {
     }
     return [...definitions];
 }
-function resolveToValues(identifier, environment, graph) {
+function resolveToValues(identifier, environment, idMap) {
     if (identifier === undefined) {
         return undefined;
     }
@@ -169,7 +169,7 @@ function resolveToValues(identifier, environment, graph) {
                 return undefined;
             }
             for (const id of def.value) {
-                const value = graph.idMap?.get(id)?.content;
+                const value = idMap?.get(id)?.content;
                 if (value !== undefined) {
                     values.push(value);
                 }
@@ -185,10 +185,10 @@ function resolveToValues(identifier, environment, graph) {
  * Convenience function using the variable resolver as specified within the configuration file
  * In the future we may want to have this set once at the start of the analysis
  */
-function resolveValueOfVariable(identifier, environment, graph) {
+function resolveValueOfVariable(identifier, environment, idMap) {
     const resolve = (0, config_1.getConfig)().solver.variables;
     switch (resolve) {
-        case config_1.VariableResolve.Alias: return resolveToValues(identifier, environment, graph);
+        case config_1.VariableResolve.Alias: return resolveToValues(identifier, environment, idMap);
         case config_1.VariableResolve.Builtin: return resolveToConstants(identifier, environment);
         case config_1.VariableResolve.Disabled: return [];
         default: (0, assert_1.assertUnreachable)(resolve);

package/dataflow/extractor.d.ts

@@ -3,5 +3,15 @@ import type { DataflowProcessors } from './processor';
 import type { NormalizedAst, ParentInformation } from '../r-bridge/lang-4.x/ast/model/processing/decorate';
 import type { RParseRequests } from '../r-bridge/retriever';
 import type { KnownParserType, Parser } from '../r-bridge/parser';
+/**
+ * The best friend of {@link produceDataFlowGraph} and {@link processDataflowFor}.
+ * Maps every {@link RType} in the normalized AST to a processor.
+ */
 export declare const processors: DataflowProcessors<ParentInformation>;
+/**
+ * This is the main function to produce the dataflow graph from a given request and normalized AST.
+ * Note, that this requires knowledge of the active parser in case the dataflow analysis uncovers other files that have to be parsed and integrated into the analysis
+ * (e.g., in the event of a `source` call).
+ * For the actual, canonical fold entry point, see {@link processDataflowFor}.
+ */
 export declare function produceDataFlowGraph<OtherInfo>(parser: Parser<KnownParserType>, request: RParseRequests, ast: NormalizedAst<OtherInfo & ParentInformation>): DataflowInformation;

package/dataflow/extractor.js

@@ -21,6 +21,10 @@ const cfg_1 = require("../util/cfg/cfg");
 const edge_1 = require("./graph/edge");
 const identify_link_to_last_call_relation_1 = require("../queries/catalog/call-context-query/identify-link-to-last-call-relation");
 const built_in_function_definition_1 = require("./internal/process/functions/call/built-in/built-in-function-definition");
+/**
+ * The best friend of {@link produceDataFlowGraph} and {@link processDataflowFor}.
+ * Maps every {@link RType} in the normalized AST to a processor.
+ */
 exports.processors = {
     [type_1.RType.Number]: process_value_1.processValue,
     [type_1.RType.String]: process_value_1.processValue,
@@ -57,7 +61,7 @@ function resolveLinkToSideEffects(ast, graph) {
         if (typeof s !== 'object') {
             continue;
         }
-        cfg ??= (0, cfg_1.extractCFG)(ast).graph;
+        cfg ??= (0, cfg_1.extractCFG)(ast, graph).graph;
         /* this has to change whenever we add a new link to relations because we currently offer no abstraction for the type */
         const potentials = (0, identify_link_to_last_call_relation_1.identifyLinkToLastCallRelation)(s.id, cfg, graph, s.linkTo);
         for (const pot of potentials) {
@@ -68,6 +72,12 @@ function resolveLinkToSideEffects(ast, graph) {
         }
     }
 }
+/**
+ * This is the main function to produce the dataflow graph from a given request and normalized AST.
+ * Note, that this requires knowledge of the active parser in case the dataflow analysis uncovers other files that have to be parsed and integrated into the analysis
+ * (e.g., in the event of a `source` call).
+ * For the actual, canonical fold entry point, see {@link processDataflowFor}.
+ */
 function produceDataFlowGraph(parser, request, ast) {
     const multifile = Array.isArray(request);
     let firstRequest;

package/dataflow/graph/dataflowgraph-builder.d.ts

@@ -85,57 +85,58 @@ export declare class DataflowGraphBuilder extends DataflowGraph {
     /**
      * Adds a **read edge** (E1).
      *
-     * @param from - Vertex/NodeId
-     * @param to   - see from
+     * @param from - NodeId of the source vertex
+     * @param to   - Either a single or multiple target ids.
+     *               If you pass multiple this will construct a single edge for each of them.
      */
     reads(from: NodeId, to: DataflowGraphEdgeTarget): this;
     /**
      * Adds a **defined-by edge** (E2), with from as defined variable, and to
      * as a variable/function contributing to its definition.
      *
-     * @see reads for parameters.
+     * @see {@link DataflowGraphBuilder#reads|reads} for parameters.
      */
     definedBy(from: NodeId, to: DataflowGraphEdgeTarget): this;
     /**
      * Adds a **call edge** (E5) with from as caller, and to as callee.
      *
-     * @see reads for parameters.
+     * @see {@link DataflowGraphBuilder#reads|reads} for parameters.
      */
     calls(from: NodeId, to: DataflowGraphEdgeTarget): this;
     /**
      * Adds a **return edge** (E6) with from as function, and to as exit point.
      *
-     * @see reads for parameters.
+     * @see {@link DataflowGraphBuilder#reads|reads} for parameters.
      */
     returns(from: NodeId, to: DataflowGraphEdgeTarget): this;
     /**
      * Adds a **defines-on-call edge** (E7) with from as variable, and to as its definition
      *
-     * @see reads for parameters.
+     * @see {@link DataflowGraphBuilder#reads|reads} for parameters.
      */
     definesOnCall(from: NodeId, to: DataflowGraphEdgeTarget): this;
     /**
      * Adds a **defined-by-on-call edge** with from as definition, and to as variable.
      *
-     * @see reads for parameters.
+     * @see {@link DataflowGraphBuilder#reads|reads} for parameters.
      */
     definedByOnCall(from: NodeId, to: DataflowGraphEdgeTarget): this;
     /**
      * Adds an **argument edge** (E9) with from as function call, and to as argument.
      *
-     * @see reads for parameters.
+     * @see {@link DataflowGraphBuilder#reads|reads} for parameters.
      */
     argument(from: NodeId, to: DataflowGraphEdgeTarget): this;
     /**
      * Adds a **non-standard evaluation edge** with from as vertex, and to as vertex.
      *
-     * @see reads for parameters.
+     * @see {@link DataflowGraphBuilder#reads|reads} for parameters.
      */
     nse(from: NodeId, to: DataflowGraphEdgeTarget): this;
     /**
      * Adds a **side-effect-on-call edge** with from as vertex, and to as vertex.
      *
-     * @see reads for parameters.
+     * @see {@link DataflowGraphBuilder#reads|reads} for parameters.
      */
     sideEffectOnCall(from: NodeId, to: DataflowGraphEdgeTarget): this;
     /**

package/dataflow/graph/dataflowgraph-builder.js

@@ -173,8 +173,9 @@ class DataflowGraphBuilder extends graph_1.DataflowGraph {
     /**
      * Adds a **read edge** (E1).
      *
-     * @param from - Vertex/NodeId
-     * @param to   - see from
+     * @param from - NodeId of the source vertex
+     * @param to   - Either a single or multiple target ids.
+     *               If you pass multiple this will construct a single edge for each of them.
      */
     reads(from, to) {
         return this.edgeHelper(from, to, edge_1.EdgeType.Reads);
@@ -183,7 +184,7 @@ class DataflowGraphBuilder extends graph_1.DataflowGraph {
      * Adds a **defined-by edge** (E2), with from as defined variable, and to
      * as a variable/function contributing to its definition.
      *
-     * @see reads for parameters.
+     * @see {@link DataflowGraphBuilder#reads|reads} for parameters.
      */
     definedBy(from, to) {
         return this.edgeHelper(from, to, edge_1.EdgeType.DefinedBy);
@@ -191,7 +192,7 @@ class DataflowGraphBuilder extends graph_1.DataflowGraph {
     /**
      * Adds a **call edge** (E5) with from as caller, and to as callee.
      *
-     * @see reads for parameters.
+     * @see {@link DataflowGraphBuilder#reads|reads} for parameters.
      */
     calls(from, to) {
         return this.edgeHelper(from, to, edge_1.EdgeType.Calls);
@@ -199,7 +200,7 @@ class DataflowGraphBuilder extends graph_1.DataflowGraph {
     /**
      * Adds a **return edge** (E6) with from as function, and to as exit point.
      *
-     * @see reads for parameters.
+     * @see {@link DataflowGraphBuilder#reads|reads} for parameters.
      */
     returns(from, to) {
         return this.edgeHelper(from, to, edge_1.EdgeType.Returns);
@@ -207,7 +208,7 @@ class DataflowGraphBuilder extends graph_1.DataflowGraph {
     /**
      * Adds a **defines-on-call edge** (E7) with from as variable, and to as its definition
      *
-     * @see reads for parameters.
+     * @see {@link DataflowGraphBuilder#reads|reads} for parameters.
      */
     definesOnCall(from, to) {
         return this.edgeHelper(from, to, edge_1.EdgeType.DefinesOnCall);
@@ -215,7 +216,7 @@ class DataflowGraphBuilder extends graph_1.DataflowGraph {
     /**
      * Adds a **defined-by-on-call edge** with from as definition, and to as variable.
      *
-     * @see reads for parameters.
+     * @see {@link DataflowGraphBuilder#reads|reads} for parameters.
      */
     definedByOnCall(from, to) {
         return this.edgeHelper(from, to, edge_1.EdgeType.DefinedByOnCall);
@@ -223,7 +224,7 @@ class DataflowGraphBuilder extends graph_1.DataflowGraph {
     /**
      * Adds an **argument edge** (E9) with from as function call, and to as argument.
      *
-     * @see reads for parameters.
+     * @see {@link DataflowGraphBuilder#reads|reads} for parameters.
      */
     argument(from, to) {
         return this.edgeHelper(from, to, edge_1.EdgeType.Argument);
@@ -231,7 +232,7 @@ class DataflowGraphBuilder extends graph_1.DataflowGraph {
     /**
      * Adds a **non-standard evaluation edge** with from as vertex, and to as vertex.
      *
-     * @see reads for parameters.
+     * @see {@link DataflowGraphBuilder#reads|reads} for parameters.
      */
     nse(from, to) {
         return this.edgeHelper(from, to, edge_1.EdgeType.NonStandardEvaluation);
@@ -239,7 +240,7 @@ class DataflowGraphBuilder extends graph_1.DataflowGraph {
     /**
      * Adds a **side-effect-on-call edge** with from as vertex, and to as vertex.
      *
-     * @see reads for parameters.
+     * @see {@link DataflowGraphBuilder#reads|reads} for parameters.
      */
     sideEffectOnCall(from, to) {
         return this.edgeHelper(from, to, edge_1.EdgeType.SideEffectOnCall);

package/dataflow/graph/edge.d.ts

@@ -78,7 +78,7 @@ export declare const enum TraverseEdge {
  *
  * Counterpart of {@link edgeDoesNotIncludeType}.
  */
-export declare function edgeIncludesType(type: EdgeTypeBits, types: EdgeTypeBits): boolean;
+export declare function edgeIncludesType(type: EdgeTypeBits, typesToInclude: EdgeTypeBits): boolean;
 /**
  * Check if the given-edge type does not include the given type.
  * Counterpart of {@link edgeIncludesType}.

package/dataflow/graph/edge.js

@@ -85,8 +85,8 @@ function edgeTypesToNames(bits) {
  *
  * Counterpart of {@link edgeDoesNotIncludeType}.
  */
-function edgeIncludesType(type, types) {
-    return (types & type) !== 0;
+function edgeIncludesType(type, typesToInclude) {
+    return (typesToInclude & type) !== 0;
 }
 /**
  * Check if the given-edge type does not include the given type.

package/dataflow/graph/vertex.d.ts

@@ -21,7 +21,7 @@ export declare const ValidVertexTypeReverse: {
  */
 export interface ContainerLeafIndex {
     /**
-     * Destinctive lexeme of index e.g 'name' for `list(name = 'John')`
+     * Distinctive lexeme of index e.g. 'name' for `list(name = 'John')`
      */
     readonly lexeme: string;
     /**
@@ -201,21 +201,21 @@ export type DataflowGraphVertices<Vertex extends DataflowGraphVertexInfo = Dataf
 /**
  * Check if the given vertex is a {@link DataflowGraphVertexValue|value vertex}.
  */
-export declare function isValueVertex(vertex: DataflowGraphVertexBase): vertex is DataflowGraphVertexValue;
+export declare function isValueVertex(vertex?: DataflowGraphVertexBase): vertex is DataflowGraphVertexValue;
 /**
  * Check if the given vertex is a {@link DataflowGraphVertexUse|use vertex}.
  */
-export declare function isUseVertex(vertex: DataflowGraphVertexBase): vertex is DataflowGraphVertexUse;
+export declare function isUseVertex(vertex?: DataflowGraphVertexBase): vertex is DataflowGraphVertexUse;
 /**
  * Check if the given vertex is a {@link DataflowGraphVertexFunctionCall|function call vertex}.
  */
-export declare function isFunctionCallVertex(vertex: DataflowGraphVertexBase): vertex is DataflowGraphVertexFunctionCall;
+export declare function isFunctionCallVertex(vertex?: DataflowGraphVertexBase): vertex is DataflowGraphVertexFunctionCall;
 /**
  * Check if the given vertex is a {@link DataflowGraphVertexVariableDefinition|variable definition vertex}.
  */
-export declare function isVariableDefinitionVertex(vertex: DataflowGraphVertexBase): vertex is DataflowGraphVertexVariableDefinition;
+export declare function isVariableDefinitionVertex(vertex?: DataflowGraphVertexBase): vertex is DataflowGraphVertexVariableDefinition;
 /**
  * Check if the given vertex is a {@link DataflowGraphVertexFunctionDefinition|function definition vertex}.
  */
-export declare function isFunctionDefinitionVertex(vertex: DataflowGraphVertexBase): vertex is DataflowGraphVertexFunctionDefinition;
+export declare function isFunctionDefinitionVertex(vertex?: DataflowGraphVertexBase): vertex is DataflowGraphVertexFunctionDefinition;
 export {};

package/dataflow/graph/vertex.js

@@ -24,30 +24,30 @@ function isParentContainerIndex(index) {
  * Check if the given vertex is a {@link DataflowGraphVertexValue|value vertex}.
  */
 function isValueVertex(vertex) {
-    return vertex.tag === VertexType.Value;
+    return vertex?.tag === VertexType.Value;
 }
 /**
  * Check if the given vertex is a {@link DataflowGraphVertexUse|use vertex}.
  */
 function isUseVertex(vertex) {
-    return vertex.tag === VertexType.Use;
+    return vertex?.tag === VertexType.Use;
 }
 /**
  * Check if the given vertex is a {@link DataflowGraphVertexFunctionCall|function call vertex}.
  */
 function isFunctionCallVertex(vertex) {
-    return vertex.tag === VertexType.FunctionCall;
+    return vertex?.tag === VertexType.FunctionCall;
 }
 /**
  * Check if the given vertex is a {@link DataflowGraphVertexVariableDefinition|variable definition vertex}.
  */
 function isVariableDefinitionVertex(vertex) {
-    return vertex.tag === VertexType.VariableDefinition;
+    return vertex?.tag === VertexType.VariableDefinition;
 }
 /**
  * Check if the given vertex is a {@link DataflowGraphVertexFunctionDefinition|function definition vertex}.
  */
 function isFunctionDefinitionVertex(vertex) {
-    return vertex.tag === VertexType.FunctionDefinition;
+    return vertex?.tag === VertexType.FunctionDefinition;
 }
 //# sourceMappingURL=vertex.js.map