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 `.` dispatch targets in the same package) */ readonly s3generic?: boolean; /** the `.` 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=`), for CRAN packages */ readonly cranPage?: string; /** the package's read-only CRAN GitHub mirror (`github.com/cran/`), 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()` 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, queryResults: BaseQueryResult, result: string[], _query: readonly import("../../query").Query[]) => true; readonly fromLine: typeof signatureQueryLineParser; readonly completer: typeof signatureQueryCompleter; readonly syntax: "@signature [[@]] [:: | ] [--param [,...]] [--required ] [--cg] [--help]"; readonly schema: Joi.ObjectSchema; readonly flattenInvolvedNodes: () => NodeId[]; }; export {};