[Query] Guess Dependency Versions

This document was generated from 'src/documentation/wiki-query.ts' on 2026-07-21, 13:40:53 UTC presenting an overview of flowR's query API (v2.13.1). Please do not edit this file/wiki page directly.

Guess Dependency Versions Query ^[overview]

Guesses the version range each dependency must have, from declared constraints and actual code usage.
This query is requested with the type guess-dep-versions.
Run in the REPL: :query @guess-dep-versions [<pkg> ...] [(clean | <=YYYY.MM.DD)] [--date YYYY.MM.DD] [--max <n>] [--iterations <n>] [--disabled <letters>] [--explode [--oldest] [--limit <n>] [--prefer <pkg>=<ver>]] <code | file://path>

A script rarely says which version of a package it needs, but it shows you. If it passes an argument that a function only gained in some release, it cannot run on anything older. This query turns that observation into a concrete version range per dependency.

It combines two sources of evidence:

1. what the project declares: a DESCRIPTION range, an rproject.toml entry, a lockfile pin, and everything these imply transitively, and
2. what the code does: which package functions it calls and with which arguments, matched against the signature database.

Every resulting bound carries its provenance, so the answer explains itself: each entry lists the evidence that produced it, naming the function, the parameter, and the bound it implies.

Two things can raise a lower bound: calling a function that did not exist yet, or passing an argument that the function only gained later. Consider a script calling dplyr::across:

library(dplyr)
mutate(mtcars, across(everything(), round))

across was only introduced in dplyr 1.0.0, so the script cannot run on anything older. The result names the function that produced the bound:

[
  {
    "type": "guess-dep-versions"
  }
]

(This can be shortened to @guess-dep-versions when used with the REPL command :query).

Show Results

Results (prettified and summarized):

Query: guess-dep-versions (1 ms)
   ╰ No signature database is loaded; version guessing needs the signature database (see the Signature Database wiki).
All queries together required ≈1 ms (1ms accuracy, total 2 ms)

Show Detailed Results as Json

The analysis required 1.9 ms (including parsing and normalization and the query) within the generation environment.

In general, the JSON contains the Ids of the nodes in question as they are present in the normalized AST or the dataflow graph of flowR. Please consult the Interface wiki page for more information on how to get those.

{
  "guess-dep-versions": {
    ".meta": {
      "timing": 1
    },
    "dependencies": [],
    "message": "No signature database is loaded; version guessing needs the signature database (see the Signature Database wiki)."
  },
  ".meta": {
    "timing": 1
  }
}

The guess can be narrowed further:

• packages restricts it to the dependencies you care about,
• date caps every guess to releases available at that point in time (YYYY.MM.DD, also YYYY or YYYY.MM),
• clean ignores the declared constraints entirely and guesses purely from usage,
• disabled excludes individual evidence sources by name (repl: --disabled followed by their one-letter codes shown in the legend below, e.g. --disabled ds drops declared and signature),
• maxCandidates caps how many candidate versions are listed per dependency,
• maxIterations bounds the two fixpoint loops (packages constrain each other, so the guess is iterated until it settles), and
• explode additionally enumerates concrete version combinations (order, prefer, and limit control which and how many).

Packages can also be tied to one shared version (the base/R packages always are), and solver.versionManagement.linkedVersionGroups declares further groups. Such a package reports its partners in linkedWith, because its range is then no longer independent of theirs.

Note

This query needs the signature database, and specifically a database carrying the history of a package, since bounding a version means comparing releases. Without one it returns no guesses and says so in its message. See the Signature Query to inspect the signatures the guess is drawn from.

Implementation Details

Responsible for the execution of the Guess Dependency Versions Query query is executeGuessDepVersionsQuery in ./src/queries/catalog/guess-dep-versions-query/guess-dep-versions-query-executor.ts.