@eagleoutice/flowr-dev/queries/catalog/dependencies-query/dependencies-query-format.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

import type { BaseQueryFormat, BaseQueryResult, BasicQueryData } from '../../base-query-format';
import type { NodeId } from '../../../r-bridge/lang-4.x/ast/model/processing/node-id';
import { type OutputFormatter } from '../../../util/text/ansi';
import Joi from 'joi';
import { executeDependenciesQuery } from './dependencies-query-executor';
import type { FunctionInfo } from './function-info/function-info';
import type { CallContextQueryResult } from '../call-context-query/call-context-query-format';
import type { Range } from 'semver';
import type { AsyncOrSync, MarkOptional } from 'ts-essentials';
import type { NamespaceInfo } from '../../../project/plugins/file-plugins/files/flowr-namespace-file';
import { Identifier } from '../../../dataflow/environments/identifier';
/** The value could not be resolved, e.g. a path assembled at runtime. Such a dependency may be missing or fetchable. */
export declare const Unknown = "unknown";
/** The value resolved, but to data given inline rather than to a path (`matrix(0, 2, 2)`, `data.frame(a = 1)`). */
export declare const Constant = "constant";
export interface DependencyCategorySettings {
    queryDisplayName?: string;
    functions: FunctionInfo[];
    /** this describes the global default value for this category, e.g., 'stdout' for write operations, please be aware, that this can be overwritten by a by-function default value */
    defaultValue?: string;
    /**
     * An optional additional analysis step that is executed after the main function-based analysis has been performed.
     * To add or modify dependency info entries, simply modify the `result` array.
     * @param data  - The basic query data.
     * @param ignoreDefault - Whether the default functions were ignored.
     * @param functions - The functions used for this category.
     * @param queryResults - The results of the call context query.
     * @param result - The current result array to which additional dependency info can be added.
     */
    additionalAnalysis?: (data: BasicQueryData, ignoreDefault: boolean, functions: FunctionInfo[], queryResults: CallContextQueryResult, result: DependencyInfo[]) => AsyncOrSync<void>;
}
export declare const DefaultDependencyCategories: {
    readonly library: {
        readonly queryDisplayName: "Libraries";
        readonly functions: FunctionInfo[];
        readonly defaultValue: "unknown";
        readonly additionalAnalysis: (data: BasicQueryData, ignoreDefault: boolean, _functions: FunctionInfo[], _queryResults: CallContextQueryResult, result: DependencyInfo[]) => Promise<void>;
    };
    readonly remote: {
        readonly queryDisplayName: "Remote Installs";
        readonly functions: FunctionInfo[];
        readonly defaultValue: "unknown";
        readonly additionalAnalysis: (_data: BasicQueryData, _ignoreDefault: boolean, _functions: FunctionInfo[], _queryResults: CallContextQueryResult, result: DependencyInfo[]) => void;
    };
    readonly source: {
        readonly queryDisplayName: "Sourced Files";
        readonly functions: FunctionInfo[];
        readonly defaultValue: "unknown";
    };
    readonly read: {
        readonly queryDisplayName: "Read Data";
        readonly functions: FunctionInfo[];
        readonly defaultValue: "unknown";
    };
    readonly write: {
        readonly queryDisplayName: "Written Data";
        readonly functions: FunctionInfo[];
        readonly defaultValue: "stdout";
    };
    readonly print: {
        readonly queryDisplayName: "Auto-printed Results";
        readonly functions: [];
        readonly defaultValue: "stdout";
        readonly additionalAnalysis: (data: BasicQueryData, ignoreDefault: boolean, _functions: FunctionInfo[], queryResults: CallContextQueryResult, result: DependencyInfo[]) => Promise<void>;
    };
    readonly visualize: {
        readonly queryDisplayName: "Visualizations";
        readonly functions: FunctionInfo[];
    };
    readonly test: {
        readonly queryDisplayName: "Tests";
        readonly functions: FunctionInfo[];
    };
};
export type DefaultDependencyCategoryName = keyof typeof DefaultDependencyCategories;
export type DependencyCategoryName = DefaultDependencyCategoryName | string;
export interface DependenciesQuery extends BaseQueryFormat, Partial<Record<`${DefaultDependencyCategoryName}Functions`, FunctionInfo[]>> {
    readonly type: 'dependencies';
    readonly enabledCategories?: DependencyCategoryName[];
    readonly ignoreDefaultFunctions?: boolean;
    /** Naming a built-in category extends it; use `ignoreDefaultFunctions` to drop the built-in functions. */
    readonly additionalCategories?: Record<string, MarkOptional<DependencyCategorySettings, 'additionalAnalysis'>>;
}
export type DependenciesQueryResult = BaseQueryResult & {
    [C in DefaultDependencyCategoryName]: DependencyInfo[];
} & {
    [S in string]?: DependencyInfo[];
};
export interface DependencyInfo extends Record<string, unknown> {
    nodeId: NodeId;
    /** the called name; an {@link Identifier}, so a namespaced call like `maps::map` keeps its package */
    functionName: Identifier;
    linkedIds?: readonly NodeId[];
    /**
     * The other statements that build this output: for a plot, the addons drawn onto it and, when it lands in a
     * file, the device opener and closer around it. Answers *which statements produce this output* without
     * rebuilding it from {@link linkedIds}.
     */
    parts?: readonly NodeId[];
    /**
     * the argument the value was read from, under the id the {@link InputSourcesQuery} reports it with: ask that
     * query about {@link nodeId} and this entry of its answer says whether the value is a glob, a prompt, ...
     */
    argumentId?: NodeId;
    /** the lexeme is presented whenever the specific info is {@link Unknown} or {@link Constant} */
    lexemeOfArgument?: string;
    /** The library name, file, source, destination etc. being sourced, read from, or written to. */
    value?: string;
    versionConstraints?: readonly Range[];
    derivedRange?: Range;
    namespaceInfo?: NamespaceInfo;
    /** the package the dependency provides, when the {@link value} names it only implicitly (a `user/repo` slug, a clone url) */
    packageName?: string;
    /** the revision such a reference pins, the `v1.2` of `user/repo@v1.2` */
    revision?: string;
}
/**
 * Gets all dependency categories, including user-defined additional categories.
 * A category named like a built-in one extends it instead of replacing it.
 */
export declare function getAllCategories(queries: readonly DependenciesQuery[]): Record<DependencyCategoryName, DependencyCategorySettings>;
export declare const DependenciesQueryDefinition: {
    readonly title: "Dependencies Query";
    readonly executor: typeof executeDependenciesQuery;
    readonly asciiSummarizer: (formatter: OutputFormatter, _analyzer: import("../../../project/flowr-analyzer").ReadonlyFlowrAnalysisProvider<import("../../../r-bridge/parser").KnownParser>, queryResults: BaseQueryResult, result: string[], queries: readonly import("../../query").Query[]) => true;
    readonly schema: Joi.ObjectSchema<any>;
    readonly flattenInvolvedNodes: (queryResults: BaseQueryResult, query: readonly import("../../query").Query[]) => NodeId[];
};