Add 'rig proj tree'

Author: gaborcsardi

NEWS.md

@@ -10,8 +10,9 @@
   table, and `rig pkg tree` shows the same dependencies as a tree.
 
 * `rig proj deps` has a new `--recursive` (`-r`) option, to show the whole
-  dependency closure of the project, like `rig pkg deps --recursive` does
-  for a package. Its table now has the same columns as `rig pkg deps`.
+  dependency closure of the project.
+
+* New `rig proj tree` shows the dependency closure of a project as a tree.
 
 * `rig library add`, `rig library default`, `rig library list` and
   `rig library rm` have a new `--r-version` (`-r`) option, to operate on

src/args.rs

@@ -1351,6 +1351,41 @@ pub fn rig_app() -> Command {
                         .required(false),
                 ),
         )
+        .subcommand(
+            Command::new("tree")
+                .about(ABOUT_PROJ_TREE)
+                .long_about(HELP_PROJ_TREE)
+                .display_order(0)
+                .arg(
+                    Arg::new("input")
+                        .help("Project file to solve (e.g. DESCRIPTION)")
+                        .long("input")
+                        .short('i')
+                        .num_args(1)
+                        .required(false),
+                )
+                .arg(
+                    Arg::new("dev")
+                        .help("Include dev (development) dependencies")
+                        .long("dev")
+                        .num_args(0)
+                        .required(false),
+                )
+                .arg(
+                    Arg::new("no-base")
+                        .help("Leave out R and the base packages")
+                        .long("no-base")
+                        .num_args(0)
+                        .required(false),
+                )
+                .arg(
+                    Arg::new("json")
+                        .help("JSON output")
+                        .long("json")
+                        .num_args(0)
+                        .required(false),
+                ),
+        )
         .subcommand(
             Command::new("solve")
                 .about(ABOUT_PROJ_SOLVE)

src/help-generated.in

@@ -35,7 +35,8 @@ and the version requirement it is needed with, if it has one.
 
 By default the tree of the latest version of the package is shown; use
 `--version` to ask about a specific one, including versions that CRAN has
-archived.
+archived. [`rig proj tree`](proj.qmd#rig-proj-tree) shows the same tree for the
+dependencies a project declares, instead of a package's.
 
 ## Repeated packages
 

src/help/pkg-tree.md

@@ -24,6 +24,10 @@ the `Depth` column giving its distance from the project, and the
 package metadata of the repositories, which rig downloads if it does not
 have it yet.
 
+[`rig proj tree`](#rig-proj-tree) shows the same closure as a tree, laid
+out by the shape of the dependency graph, so you can see *how* each
+package is pulled in and not only *that* it is.
+
 A recursive listing only ever follows hard dependencies, also below a
 development dependency added by `--dev`, so `--dev --recursive` means the
 project's own dev dependencies plus everything they need to be installed.

src/help/proj-deps.md

@@ -0,0 +1,62 @@
+Dependency tree of a project
+
+## Description
+
+Show everything an R project needs, directly or indirectly, as a tree, so you
+can see *how* each package is pulled in and not only *that* it is.
+
+This is the same set of packages that
+[`rig proj deps --recursive`](#rig-proj-deps) lists in a flat table, laid out by
+the shape of the dependency graph instead. Use `--json` for machine readable
+output, as one nested object.
+
+```
+myproject 0.1.0 — 3 direct, 24 total
+├── R (>= 4.1) [D]
+├── cli 3.6.4
+│   ├── R (>= 3.4) [D]
+│   └── utils
+└── dplyr 1.1.4 (>= 1.1.0)
+    ├── cli 3.6.4 (>= 3.4.0) (*)
+    └── vctrs 0.6.5 (>= 0.6.4)
+        └── cpp11 0.5.2 [L]
+[Suggests]
+└── testthat 3.2.3 (>= 3.1.5)
+```
+
+The first line names the project and its version, how many dependencies it
+declares directly, and how many distinct packages there are in the whole tree.
+Each line below it names a package, the version currently in the repositories,
+and the version requirement it is needed with, if it has one.
+
+By default rig reads the project manifest (e.g. `DESCRIPTION`) in the current
+directory; use `--input` to point to a different file. Unlike the plain
+[`rig proj deps`](#rig-proj-deps) listing, the tree needs the package metadata
+of the repositories, which rig downloads if it does not have it yet. It does
+not need R.
+
+## Reading the tree
+
+A package that several others need is expanded only once, under the first
+place it appears; later occurrences are a single line marked `(*)`, meaning
+"its dependencies are above". That is also what makes dependency cycles end on
+their own.
+
+`--dev` adds the project's development dependencies, `Suggests` and `Enhances`,
+in their own `[Suggests]` and `[Enhances]` sections. As in `rig proj deps`,
+`--dev` applies to the project only: below a development dependency rig still
+follows hard dependencies only. `--no-base` leaves out R and the base packages
+altogether, which is much less to read if you only care about what would have
+to be installed. A package that is not in the repositories at all is shown with
+`?` for its version.
+
+Among the hard dependencies, `Imports` is the common case and is not marked;
+`[D]` is a `Depends`, `[L]` a `LinkingTo`, `[DL]` both.
+[`rig pkg tree`](pkg.qmd#rig-pkg-tree), which shows the same tree for a package
+in the repositories, describes all of this in full.
+
+rig follows the dependencies of the *latest* version of every package in the
+tree, so a version requirement that would force an older version, with
+different dependencies, is not taken into account. Use
+[`rig proj solve`](#rig-proj-solve) for a resolution that is consistent across
+versions.

src/help/proj-tree.md

@@ -11,13 +11,15 @@ repositories and can install them into a project library.
 
 `rig proj deps` shows the direct and recursive dependencies of the
 project.
+`rig proj tree` shows the recursive dependencies as a tree, so you can
+see how each package is pulled in.
 `rig proj solve` resolves the full dependency tree to a concrete set of
 package versions, and can write the result to an `renv.lock` file.
 `rig proj deploy` installs the resolved dependencies into a package
 library.
 
 Dependencies are resolved with rig's built-in solver, so R does not need
-to be running for `rig proj deps` and `rig proj solve`.
+to be running for `rig proj deps`, `rig proj tree` and `rig proj solve`.
 
 `rig proj` is currently experimental, and might change in future
 versions. Feedback is appreciated.

src/help/proj.md

@@ -212,6 +212,14 @@ pub(super) fn recursive_dep_names(
     Ok(rows.into_iter().map(|row| row.name).collect())
 }
 
+/// The packages of a [`walk_deps`] listing, by name. Lets [`super::tree`] check
+/// that a project tree walks the same closure `rig proj deps --recursive` does,
+/// without exposing [`DepRow`]'s fields outside the module.
+#[cfg(test)]
+pub(super) fn dep_row_names(rows: &[DepRow]) -> Vec<String> {
+    rows.iter().map(|row| row.name.clone()).collect()
+}
+
 /// Record `dep` as a dependency of `parent`, `depth` steps from the queried
 /// package, and return whether this is the first time we see it.
 ///

src/pkg/deps.rs

@@ -23,7 +23,7 @@ pub(crate) mod deps;
 mod manifest;
 #[cfg(test)]
 mod stub;
-mod tree;
+pub(crate) mod tree;
 
 pub fn sc_pkg(args: &ArgMatches, mainargs: &ArgMatches) -> Result<(), Box<dyn Error>> {
     match args.subcommand() {