@eagleoutice/flowr-dev/reconstruct/inline/source-inline-map.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

/**
 * Maps each `source()` call node to the index of the file it sources in `ast.ast.files`.
 * {@link reconstructToCode} uses it (via `inlineSources`) to splice a sourced file's reconstruction
 * in place of its `source()` call, yielding one self-contained R text.
 * @module
 */
import type { NormalizedAst } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
import type { DataflowGraph } from '../../dataflow/graph/graph';
import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
/**
 * A warning raised while inlining `source()` calls during reconstruction.
 * @see {@link reconstructToCode}
 */
export interface InlineWarning {
    /**
     * - `cycle`: the `source()` would re-inline a file already being inlined on the current path;
     *   the literal call is kept at the cycle edge to break the recursion.
     * - `unresolved`: the `source()` survived the slice but could not be linked to a file
     *   (dynamic or missing path); the literal call is kept verbatim.
     */
    readonly kind: 'cycle' | 'unresolved';
    /** the id of the `source()` function-call node that triggered the warning */
    readonly callId: NodeId;
    /** the (best-effort) path of the file that was meant to be sourced, if known */
    readonly path?: string;
}
/**
 * Helper functions to link `source()` calls to the files they source for reconstruction inlining.
 * @see {@link SourceInlineMap.build}
 */
export declare const SourceInlineMap: {
    readonly name: "SourceInlineMap";
    /**
     * Connect each `source()` call node to the index of the file it sources in `ast.ast.files` (index 0 is main).
     *
     * A `source()` call lives in its parent file, so we reach its sourced block via the control dependency the
     * dataflow analysis adds (see {@link sourceRequest}): a vertex whose innermost cd (`cds[0]`) is a source call
     * belongs to that call's directly sourced block. Every node carries its resolved file in `info.file`, so the
     * block's `info.file` names the sourced file independent of the call site, and one graph pass resolves all
     * calls via small map lookups. A file sourced from several sites is stored once but each block still tags the
     * same `info.file`, so all sites map to that single index (this also drives cycle detection: a re-sourcing
     * call resolves to an already-visited index).
     * @param ast   - the normalized (multi-file) ast
     * @param graph - the dataflow graph for `ast`
     * @returns a map from each `source()` call node id to the index of the sourced file in `ast.ast.files`
     */
    readonly build: (ast: NormalizedAst, graph: DataflowGraph) => Map<NodeId, number>;
};