@eagleoutice/flowr/queries/catalog/input-sources-query/simple-input-classifier.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

import type { NodeId } from '../../../r-bridge/lang-4.x/ast/model/processing/node-id';
import type { DataflowGraph } from '../../../dataflow/graph/graph';
import type { MergeableRecord } from '../../../util/objects';
import { Identifier } from '../../../dataflow/environments/identifier';
import type { FlowrSearchLike } from '../../../search/flowr-search-builder';
/**
 * Lattice flattening until we have a taint engine :)
 * Please note that the classifier considers this basis with a set-lift,
 * joining differing lattice elements.
 *
 *```
 *              [ Unknown ]
 *                   |
 * [Param] [File] [Net] [User], ...
 *                   |
 *            [ DerivedConstant ]
 *                   |
 *              [ Constant ]
 *```
 *
 */
export declare enum InputType {
    Parameter = "param",
    File = "file",
    Network = "net",
    Random = "rand",
    /** Calls to system/system2 and similar */
    System = "system",
    /** Calls to .C / Fortran interfaces (foreign function interfaces) */
    Ffi = "ffi",
    /** Language objects (quote/substitute/etc.) */
    Lang = "lang",
    /** Global options / option accessors (options, getOption) */
    Options = "options",
    /** Interactive user input (file choosers, prompts, dialogs, menu selections) */
    User = "user",
    Constant = "const",
    /** Read from environment/call scope */
    Scope = "scope",
    /** Pure calculations from constants that lead to a constant */
    DerivedConstant = "dconst",
    Unknown = "unknown"
}
export declare enum InputTraceType {
    /** Derived only from aliasing */
    Alias = "alias",
    /** Derived from pure function chains */
    Pure = "pure",
    /** Derived from known but not necessarily all pure function chains */
    Known = "known",
    /** Not fully known origin */
    Unknown = "unknown"
}
/**
 * Scalar R constant values representable in TypeScript.
 * `null` corresponds to R's `NULL`.
 * NA values are not included (they have no direct TS equivalent).
 */
export type ConstantValue = string | number | boolean | null;
/**
 * Object attached to an input source
 * @see {@link InputSources}
 */
export interface InputSource extends MergeableRecord {
    id: NodeId;
    types: InputType[];
    trace: InputTraceType;
    /** if the trace is affected by control dependencies, they are classified too, this is a duplicate free array */
    cds?: InputType[];
    /** the concrete scalar value when the source is a constant or a pure alias of one */
    value?: ConstantValue;
}
/**
 * Map of input sources, keyed by the node id of the input source. Each input source is classified with an {@link InputSource} object.
 */
export type InputSources = InputSource[];
/**
 * This is either an {@link NodeId|id} of a known functions all of that category (e.g., you can issue a dependencies query before and then pass all
 * identified ids to this query here).
 */
export type InputClassifierFunctionIdentifiers = readonly (Identifier | NodeId)[];
/**
 * For the specifications of `pure` etc. please have a look at {@link InputClassifierFunctionIdentifiers}.
 */
export interface InputClassifierConfig<Functions extends InputClassifierFunctionIdentifiers | FlowrSearchLike = readonly Identifier[] | FlowrSearchLike> extends Partial<Record<InputType, Functions>> {
    /**
     * Functions which are considered to be pure (i.e., deterministic, trusted, safe, idempotent on the lub of the input types)
     */
    [InputTraceType.Pure]?: Functions;
}
/**
 * Takes the given id which is expected to either be:
 * - a function call - in this case all arguments are considered to be inputs (additionally to all read edges from the function call in the dataflow graph)
 * - anything else - in that case the node itself is considered as an "input" - please note that in these scenarios the *return* value will only contain one mapping - that for the id you passed in.
 *
 * This method traces the dependencies in the dataflow graph using the specification of functions passed in.
 * For the scope escape analysis, pass on the full, non-reduced DFG as `fullDfg`.
 */
export declare function classifyInput(id: NodeId, dfg: DataflowGraph, config: InputClassifierConfig<InputClassifierFunctionIdentifiers>, fullDfg?: DataflowGraph): InputSources;