@eagleoutice/flowr-dev/linter/rules/undefined-symbol.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

import type { MergeableRecord } from '../../util/objects';
import type { FlowrSearchElement } from '../../search/flowr-search';
import type { ParentInformation } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
import { type LintingResult, LintingRuleCertainty } from '../linter-format';
import { LintingRuleTag } from '../linter-tags';
/** whether the flagged symbol is used in a function-call position or as a plain variable */
export type UndefinedSymbolKind = 'function' | 'variable';
export interface UndefinedSymbolResult extends LintingResult {
    /** the name that could not be resolved */
    name: string;
    /** whether the name is used as a function call or as a variable read */
    kind: UndefinedSymbolKind;
    /** packages that export this name - a hint that a `library()`/`::` might be missing (empty if none known) */
    availableInPackages?: readonly string[];
    /** an unresolved `library()` is in scope that could define this name; treat as low-confidence */
    mayBeProvidedByUnresolvedLibrary?: boolean;
}
export interface UndefinedSymbolConfig extends MergeableRecord {
    /** flag names used in a function-call position that cannot be resolved (default `true`) */
    checkFunctions: boolean;
    /**
     * flag names used as a variable read that cannot be resolved (default `true`). Formulas and data-masking
     * (dplyr/tidyr/ggplot, `subset`/`with`) are recognised via flowR's dataflow, so this is precise; residual
     * false positives are possible in dynamic `eval`/`attach`.
     */
    checkVariables: boolean;
    /**
     * flag unresolved symbols used as `[`/`[[` subscripts (default `false`). Off by default to mute
     * `data.table`'s `DT[i, j, by]` column masking, which flowR cannot distinguish from ordinary indexing.
     */
    checkSubscripts: boolean;
}
/** Why unresolved candidates were suppressed instead of reported, kept in the metadata for auditability. */
export interface SuppressionCounts {
    /** file below `inst/` (installed resource, not namespace source) */
    installed: number;
    /** exported by a package in scope: a loaded/DESCRIPTION package or a default-attached base package */
    loadedPackage: number;
    /** unconditionally bound in an enclosing scope that flowR's dataflow did not statically link */
    enclosingScope: number;
    /** consumed by non-standard evaluation (a quoting edge) */
    nonStandardEval: number;
    /** used as a `[`/`[[` subscript (muted `data.table`-style column masking) */
    subscript: number;
}
export interface UndefinedSymbolMetadata extends MergeableRecord {
    totalFunctionCalls: number;
    totalVariableUses: number;
    /** breakdown of unresolved candidates that were suppressed rather than reported */
    suppressed: SuppressionCounts;
}
/**
 * Flags function calls (`sd()`) and, opt-in, variable reads (`x`) that are neither defined locally, a
 * builtin, nor exported by a package in scope - the DESCRIPTION/`library()` packages plus the default-attached
 * base packages, all resolved from the `flowr-sigdb` database. To stay precise it consults flowR's dataflow:
 * non-standard evaluation (quoting) is not reported, and an unloaded package that exports the name is offered
 * as a hint. Over-approximative: NSE beyond what flowR models can still cause false positives.
 */
export declare const UNDEFINED_SYMBOL: {
    readonly createSearch: (_config: UndefinedSymbolConfig) => import("../../search/flowr-search-builder").FlowrSearchBuilder<"all", ["filter"], ParentInformation, Promise<import("../../search/flowr-search").FlowrSearchElements<ParentInformation, [] | FlowrSearchElement<ParentInformation>[]>>>;
    readonly processSearchResult: (elements: import("../../search/flowr-search").FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>, config: UndefinedSymbolConfig, data: import("../../project/flowr-analyzer").ReadonlyFlowrAnalysisProvider<import("../../r-bridge/parser").KnownParser>) => Promise<{
        results: UndefinedSymbolResult[];
        '.meta': UndefinedSymbolMetadata;
    }>;
    readonly prettyPrint: {
        readonly query: (result: UndefinedSymbolResult) => string;
        readonly full: (result: UndefinedSymbolResult) => string;
    };
    readonly info: {
        readonly name: "Undefined Symbol";
        readonly certainty: LintingRuleCertainty.OverApproximative;
        readonly description: "Flags functions and variables that are neither defined locally, a base R builtin, nor exported by a loaded package.";
        readonly tags: readonly [LintingRuleTag.Bug, LintingRuleTag.Experimental];
        readonly defaultConfig: {
            readonly checkFunctions: true;
            readonly checkVariables: true;
            readonly checkSubscripts: false;
        };
    };
};