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

Static Dataflow Analyzer and Program Slicer for the R Programming Language

import type { BaseQueryFormat, BaseQueryResult } from '../../base-query-format';
import type { ShardStatus } from '../../../project/sigdb/reader';
import Joi from 'joi';
import type { NodeId } from '../../../r-bridge/lang-4.x/ast/model/processing/node-id';
import type { ParsedQueryLine } from '../../query';
import type { ReplOutput } from '../../../cli/repl/commands/repl-main';
import type { FlowrConfig } from '../../../config';
import { executeSignatureQuery, signatureQueryCompleter } from './signature-query-executor';
/**
 * Inspects the loaded signature database(s) (see the {@link https://github.com/flowr-analysis/flowr/wiki/Signature-Database|Signature Database wiki}).
 * The `package` and `function` fields accept glob wildcards (`*`, `?`), and `version` accepts an exact version,
 * a glob (`3.*`), a semver range (`>=3.0.0`, `3.x`), or a release-date bound (`<=2026`, `>=2021.05`, YYYY.MM.DD).
 * With no `package` it summarizes the loaded databases; a single exact package/function yields the full view
 * (signature, definition location, CRAN-mirror source link); a wildcard yields the matching set. `parameters` and `requiredParameters` further filter to
 * functions that have a parameter matching *every* given name (position-independent) or an exact required-parameter
 * count (a parameter filter alone, e.g. `--param fuzz`, searches every package; repeat `--param` or comma-separate
 * to require several, e.g. `--param data --param mapping`).
 */
export interface SignatureQuery extends BaseQueryFormat {
    readonly type: 'signature';
    /** the package to inspect (glob wildcards allowed); omit for a summary of the loaded databases */
    readonly package?: string;
    /** the function/symbol within {@link package} to inspect (glob wildcards allowed) */
    readonly function?: string;
    /** a version spec: an exact version, a glob (`3.*`), a semver range (`>=3.0.0`, `3.x`), or a release-date bound (`<=2026`, `>=2021.05` in YYYY.MM.DD) */
    readonly version?: string;
    /** keep only functions that have a parameter matching *every* one of these names (glob wildcards allowed, position-independent, e.g. `fuzz`, `.*data`) */
    readonly parameters?: readonly string[];
    /** keep only functions with exactly this many required (no-default) parameters, excluding `...` */
    readonly requiredParameters?: number;
    /** for a single function, also render its transitive call graph as a mermaid.live link (`--cg`) */
    readonly callGraph?: boolean;
}
/** one parameter of a function signature */
export interface SignatureParameterView {
    readonly name: string;
    readonly required: boolean;
    readonly forced: boolean;
    readonly default?: string;
}
/** the detailed view of a single function within a package */
export interface SignatureFunctionView {
    readonly name: string;
    readonly package: string;
    readonly version?: string;
    readonly exported: boolean;
    readonly properties: readonly string[];
    readonly parameters: readonly SignatureParameterView[];
    readonly callees: readonly string[];
    readonly file?: string;
    readonly line?: number;
    /** deep link to the definition on the read-only GitHub mirror of the sources (CRAN, or R's own for a base package) */
    readonly sourceUrl?: string;
    /** best-effort rdrr.io documentation link, when the function name maps to a documentable topic */
    readonly docUrl?: string;
    /** link to the `.Rd` help source *at the queried version*, which {@link docUrl} cannot offer (rdrr.io only serves the current release) */
    readonly manUrl?: string;
    /** whether the function looks like an S3 generic (has `<generic>.<class>` dispatch targets in the same package) */
    readonly s3generic?: boolean;
    /** the `<generic>.<class>` dispatch targets found in the same package */
    readonly s3methods?: readonly string[];
    /** when the function is an S3 method, the generic it dispatches for (`print.rema` is `print` in `base`, class `rema`); lazily computed */
    readonly s3method?: {
        readonly generic: string;
        readonly class: string;
        readonly package: string;
    };
    /** a mermaid.live link visualizing the transitive call graph from this function (only when requested with `--cg`) */
    readonly callGraph?: string;
    /** what flowR itself states about the function, from the built-in environment of the analysis */
    readonly flowr?: SignatureFlowrView;
    /**
     * whether the whole view comes from flowR's built-in definition because the database has no entry: the
     * primitives and operators (`+`, `[`, `if`) that appear in no package's sources, and anything a flowR
     * configuration adds. Everything the database would contribute (defaults, callees, location) is then empty,
     * and since flowR records no defaults, every {@link SignatureParameterView.required} reads `false`.
     */
    readonly flowrOnly?: boolean;
}
/**
 * What flowR knows about a function on its own, next to what the database records: the properties of the
 * call and what it uses each argument for. Read from the built-in environment of the analysis, so a
 * configured or overwritten built-in is what shows up here.
 */
export interface SignatureFlowrView {
    /** the {@link CallProp} names the built-in definition carries, like `pure` or `reads` */
    readonly props: readonly string[];
    /** the {@link ArgProp} names of every parameter flowR declares, in order; a parameter it says nothing about has no roles */
    readonly args?: readonly {
        readonly name: string;
        readonly roles: readonly string[];
    }[];
    /** the parameter handed back as the result ({@link ArgProp.Alias}), which is what draws the `Returns` edge */
    readonly returns?: string;
    /** flowR's own parameter names, only present when they disagree with the ones the database records */
    readonly parameters?: readonly string[];
}
/** one declared dependency of a package */
export interface SignatureDependencyView {
    readonly type: string;
    readonly name: string;
    readonly constraint?: string;
}
/** the full view of a package as stored in the signature database */
export interface SignaturePackageView {
    readonly name: string;
    readonly version: string;
    /** the version the analyzer resolved the package to, if it differs from {@link version} */
    readonly resolved?: string;
    readonly base: boolean;
    readonly cran: boolean;
    /** the CRAN source tarball url, when known */
    readonly cranUrl?: string;
    /** the CRAN package landing page (`cran.r-project.org/package=<pkg>`), for CRAN packages */
    readonly cranPage?: string;
    /** the package's read-only CRAN GitHub mirror (`github.com/cran/<pkg>`), for CRAN packages */
    readonly repoUrl?: string;
    readonly releaseDate?: string;
    readonly exportsTotal: number;
    readonly functionCount: number;
    readonly constants: readonly string[];
    readonly internalCount: number;
    readonly deprecated: readonly string[];
    /** for a base package: the R releases it was part of core, ascending */
    readonly coreVersions?: readonly string[];
    readonly dependencies: readonly SignatureDependencyView[];
    /**
     * The packages that end up on the search path together with this one, so that {@link exportsTotal} is not
     * mistaken for everything `library(<name>)` brings into scope (see `attachedAlongside`).
     */
    readonly attaches?: readonly string[];
    readonly functions: readonly SignatureFunctionView[];
}
/** a compact hit from a wildcard function search */
export interface SignatureMatchView {
    readonly package: string;
    readonly name: string;
    readonly exported: boolean;
    readonly version?: string;
    readonly file?: string;
    readonly line?: number;
    readonly sourceUrl?: string;
    /** best-effort rdrr.io documentation link, when the function name maps to a documentable topic */
    readonly docUrl?: string;
    /** link to the `.Rd` help source at the queried version, see {@link SignatureFunctionView.manUrl} */
    readonly manUrl?: string;
    /** a preview of the function's parameters (the ones a parameter/required filter matched first), when such a filter is active */
    readonly parameters?: readonly string[];
    /** the subset of {@link parameters} that the `--param` filter actually matched, so the renderer can highlight them */
    readonly matchedParameters?: readonly string[];
}
/** a hit from a wildcard package search */
export interface SignaturePackageMatch {
    readonly name: string;
    readonly base: boolean;
    readonly cran: boolean;
    readonly latest?: string;
    /** the versions matching the version spec (present only for a versioned search) */
    readonly versions?: readonly string[];
    readonly cranPage?: string;
}
/** metadata of one loaded signature database */
export interface SignatureDatabaseView {
    readonly scope: string;
    readonly version: number;
    readonly date: string;
}
export interface SignatureQueryResult extends BaseQueryResult {
    readonly databases: readonly SignatureDatabaseView[];
    readonly packageCount: number;
    readonly sourceCount: number;
    /** per-shard load state of the sharded sources (which shards this session has opened and unpacked); summary only */
    readonly shards?: readonly ShardStatus[];
    /** set when a single package was requested and found */
    readonly package?: SignaturePackageView;
    /** set when a single function was requested and found */
    readonly function?: SignatureFunctionView;
    /** function hits from a wildcard search */
    readonly matches?: readonly SignatureMatchView[];
    readonly matchCount?: number;
    /** how many functions the search examined against the filters (only interesting when it exceeds the hit count) */
    readonly searched?: number;
    /** whether the search covered only the latest version of each package, so historical releases were skipped */
    readonly latestOnly?: boolean;
    /** package hits from a wildcard package search (no function given) */
    readonly packages?: readonly SignaturePackageMatch[];
    /** whether the match list was capped */
    readonly truncated?: boolean;
    /** a not-found / disabled note, with optional near-match suggestions */
    readonly message?: string;
    readonly suggestions?: readonly string[];
}
/** parse a signature-query repl line into a query: `pkg`, `pkg fn`, `pkg::fn`, `pkg@ver`, globs */
declare function signatureQueryLineParser(output: ReplOutput, line: readonly string[], _config: FlowrConfig): ParsedQueryLine<'signature'>;
export declare const SignatureQueryDefinition: {
    readonly title: "Signature Query";
    readonly executor: typeof executeSignatureQuery;
    readonly asciiSummarizer: (formatter: import("../../../util/text/ansi").OutputFormatter, _analyzer: import("../../../project/flowr-analyzer").ReadonlyFlowrAnalysisProvider<import("../../../r-bridge/parser").KnownParser>, queryResults: BaseQueryResult, result: string[], _query: readonly import("../../query").Query[]) => true;
    readonly fromLine: typeof signatureQueryLineParser;
    readonly completer: typeof signatureQueryCompleter;
    readonly syntax: "@signature [<pkg>[@<version>]] [<pkg>::<fn> | <fn>] [--param <name>[,...]] [--required <n>] [--cg] [--help]";
    readonly schema: Joi.ObjectSchema<any>;
    readonly flattenInvolvedNodes: () => NodeId[];
};
export {};