rust-recursive-deps-updater 0.1.1

A fast, safe, zero-privilege recursive Cargo dependency updater for Rust workspaces and standalone crates.
Documentation

Rust Recursive Dependency Updater (rrdu)

A fast, zero-privilege CLI tool and GitHub Action to inspect, navigate, and recursively update dependencies across Rust workspaces and multi-crate repositories.


This project is in ongoing development. New versions can have breaking changes.
We provide an explaining migration guide.

Features

  • Workspace & Multi-Crate Discovery: Automatically scans the root manifest, all workspace members, and standalone nested crates across the entire repository.
  • Zero-Privilege & Sandboxed: Runs purely in user space without requiring root or administrator rights. Built with #![forbid(unsafe_code)] at the core and strict path-traversal prevention. Headless CI mode is completely free of unsafe code, while interactive mode isolates terminal dependencies (dialoguer, indicatif) with defensive TTY checks and signal recovery fallbacks.
  • Intelligent SemVer Classification: Distinguishes between compatible updates ([No migration needed]) and breaking changes ([Need manual migration]) based on official Cargo SemVer conventions.
  • Formatting-Preserving Manifest Updates: Powered by toml_edit to ensure all comments, inline tables, whitespace, and formatting in Cargo.toml remain completely intact.
  • Interactive CLI with Pagination: Terminal interface with in-place overwriting, keyboard-driven navigation (arrow keys ↑/↓ for items, ←/→ for pages, configurable max-lines), visual spinners, Backspace navigation, and clean Esc or Ctrl+C terminal restoration.
  • Two-Tier Registry Strategy: Ultra-fast, zero-latency execution in CI pipelines via the static crates.io Sparse Index (https://index.crates.io/). Rich metadata queries in interactive mode strictly throttled to 1 request/second adhering to the official crates.io Data Access Policy.
  • RustSec Security Advisory Checks: Integrates package vulnerability audits directly from rustsec.org to report known security patches, CVEs, and affected SemVer ranges.
  • Persistent Tri-Cache: Strongly-typed user-space cache (~/.rrdu/cache/) with TTL expiration checks (24h for crates.io index/API, 6h for security advisories) to eliminate redundant network calls across sessions.
  • Asynchronous Trace Logging & Structured Status Codes: Pure safe Rust async logging engine (src/logger/) with typed module status codes (1YXX - 8YXX) and non-blocking Tokio MPSC queuing (mpsc::channel(5000)). Log entries are processed by a dedicated background worker writing to ./audit/rrdu.log with automatic 1 MB log splitting and timestamped archive rotation (rrdu_yyyy_mm_dd_hh_mm_ss_ms.log) when --trace or --report is enabled.
  • Headless CI & GitHub Action: Dedicated non-interactive audit execution (--headless) providing a clean tabular report for CI/CD gates, running 100% free of unsafe TTY calls.
  • Integrated Self-Update: Update rrdu directly to the newest release with rrdu --self-update.
  • Dynamic Terminal & CI Table Reporting: Powered by comfy-table-inline (a custom release of comfy-table integrating native inline table support) with Table::force_no_tty by default in headless mode to guarantee zero unsafe ioctl calls, while delivering beautiful auto-wrapping layouts, clean borders, and SemVer status highlights across both interactive and headless CI modes.

Installation

Pre-compiled Binaries (Linux & Windows)

Download the latest pre-compiled binary from GitHub Releases.

Via Cargo

cargo install rust-recursive-deps-updater

GitHub Marketplace Action

Include rrdu directly in your GitHub Actions workflows:

- name: Check Rust Dependencies
  uses: AnnoDomine/rust-recursive-deps-updater@v1
  with:
    version: 'latest' # Optional: pin to a release tag like v0.0.6

Usage

1. Interactive Mode

Run rrdu inside your Rust workspace root without arguments:

rrdu
Key Workspace, Project and Section overview Dependency overview
Esc / Ctrl+C / Cmd+C Quit RRDU Quit RRDU
Backspace Prev View Prev View
Enter / Return Change view to selected Item n/a
Arrow Up Select prev item Scroll up
Arrow Down Select next item Scroll down
Home Select first item Scroll to top
End Select last item Scroll to bottom
Page Up Change to prev page Scroll one page up
Page down Change to next page Scroll one page down
Arrow Left n/a Select prev tab
Arrow Right n/a Select next tab
Keyboard u Update dependency Update dependency

2. Configuration Initialization

Generate a tailored, documented rrdu.toml file by scanning the workspace:

rrdu --init

3. Configuration Migration (--migrate)

Migrate an existing .rrduconfig (YAML) located at the current folder level to the modern rrdu.toml format:

rrdu --migrate

[!CAUTION] The legacy .rrduconfig file is irrevocably deleted once rrdu.toml is written. We recommend creating your own backup prior to running --migrate.

4. Headless CI / Audit Mode

Automate dependency health checks in your CI pipelines:

# Run non-interactive dependency check with audit table (exits with code 1 if outdated, 0 if up to date)
rrdu --headless

Note: Scans and cached API queries are performed automatically upon launch. To protect your codebase from unintended automated modifications, dependency updates are never applied unattended; all updates must be validated and confirmed by the user in interactive mode (rrdu).

5. Self-Update

Check for newer releases on GitHub Releases or crates.io and update the installed binary in-place:

rrdu --self-update
  • Interactive Update Notification: When launching rrdu in interactive mode and an update is detected, an informative summary table is displayed with release notes before continuing.
  • Dedicated Self-Update Menu (--self-update): Displays a focused terminal interface offering:
    • g: Update in-place via GitHub Releases (downloads pre-compiled release binary and replaces executable atomically).
    • c: Update via Cargo from crates.io (cargo install rust-recursive-deps-updater).
    • q or Esc: Abort update and exit cleanly.

6. Diagnostics & Bug Report

Generate an anonymized diagnostic report to paste into GitHub issues (paths are strictly sanitized to protect privacy):

rrdu --report

7. Trace File Logging

Enable background trace logging to ./audit/rrdu.log with automatic 1 MB splitting and timestamped archives:

rrdu --trace

8. Command Help

Display a formatted reference of all available commands, options, and descriptions:

rrdu --help

Configuration (rrdu.toml)

[!NOTE] rrdu.toml is the active standard configuration format. The legacy .rrduconfig (YAML) format is deprecated and will be removed in a future release. Existing .rrduconfig files continue to be supported in-memory for backwards compatibility, or can be migrated via rrdu --migrate. See MIGRATION.md.

You can place an optional rrdu.toml file in your repository root to configure workspace members, exclusions, and runner settings:

# Schema for editor autocompletion and validation (Taplo / Even Better TOML)
#:schema https://annodomine.github.io/rust-recursive-deps-updater/schemas/rrdu.schema.json

# List single 'Cargo.toml' workspaces
[workspaces]
rust-recursive-deps-updater = { label = "rrdu", path = "./", exclude = { project = ["comfy-table-inline", "rustls"] } }

# List single 'rrdu.toml' or legacy ".rrduconfig" sub-workspaces
[configs]
# sub-crate = "crates/sub"

# 'rrdu' workspace configuration
[rrdu]
max-lines = 10
version = "0.1.0"
exclude = ["target", "vendor"]

Configuration Options

Setting Type Description
workspaces.<key>.path path Path to the directory containing Cargo.toml or directly to Cargo.toml (required)
workspaces.<key>.label string Optional human-readable display label (defaults to project key)
workspaces.<key>.exclude.project list Crate names excluded from updates across the entire project (optional)
workspaces.<key>.exclude.section mapping Section-specific exclusions (e.g. dev-dependencies, table sections) (optional)
configs.<label> path Path to a sub-project directory or configuration file providing its own rrdu.toml (optional)
rrdu.max-lines int Maximum items displayed per page in interactive mode (default: 10)
rrdu.version string Version of rrdu the config was created with, used for compatibility checks
rrdu.exclude list Folders to completely skip during recursive scans (optional)

Naming convention

Our definitions following a specified naming convention to remove confusion.

  • scan: A scan names the flow to collect and scan dependencies for update check.
  • discovery: discoveries are crawling to the workspace folder and the sub folders to identify Cargo.toml and configuration files (rrdu.toml or legacy .rrduconfig).
  • update: The update process is the flow to update the Cargo.toml dependencies.
  • workspace: A workspace is the identification list of projects based on the related configuration file.
  • project: projects are single identified Cargo.toml files and configuration entries.

Upcoming Major Milestone: Version 0.2.0

We have major architectural evolutions and new capabilities planned for the upcoming release v0.2.0:

  • Core Cargo Crate Refactoring: Embedding the official cargo binary/crate as a direct library dependency. Refactoring core workspace traversal and dependency graph modeling onto the cargo crate delivers significant performance gains, true workspace-native resolution, and optimal memory efficiency.
  • Interactive Workspace Dependency Management: Building directly on native cargo crate integration, rrdu will introduce dynamic dependency addition and deletion (Add/delete deps in workspace in interactive mode) within the interactive interface.
  • Desktop GUI via Dioxus (--ui): An optional modern Desktop Graphical User Interface built with Dioxus on top of the interactive core, delivering rich workspace visualization, enhanced UX/UI, and full digital accessibility (screen reader compatibility, dynamic font scaling, and high-contrast theming).

Security

Security and supply chain integrity are top priorities for rrdu:

  • User-Space Only: The tool operates entirely within the user's privilege boundary. It never requires or requests root/admin privileges.
  • 100% Safe Rust Core Logic: The entire internal codebase is compiled under strict #![forbid(unsafe_code)].
  • Zero-Unsafe Headless Mode: In --headless / CI mode, rrdu completely avoids any unsafe code paths or low-level TTY interactions, enforcing Table::force_no_tty to eliminate unsafe libc/ioctl calls across automated pipelines.
  • Audited Interactive Mode with Protective Fallbacks: Interactive terminal capabilities (arrow keys, spinners, in-place overwriting) rely on established terminal dependencies (dialoguer, indicatif). Because their underlying layers (console, libc, windows-sys) interact with OS TTY modes via FFI, rrdu actively minimizes potential risks by implementing defensive fallbacks:
    • Validates interactive TTY attachments (Term::is_term()) to avoid raw-mode/ioctl failures in redirected streams or pipes.
    • Implements signal trapping (Ctrl+C / cancellation) to reliably restore terminal state, reset cursor visibility, and exit with code 2.
  • Path Traversal Protection: Relative paths are strictly validated to prevent directory traversal (../) attacks.
  • No Dynamic Injection: Operational settings are statically bound to configuration files.
  • Secure Networking & Rate Limiting: Strict TLS 1.2/1.3, compliant user-agent headers, strict 10s query timeouts, and 1-second request throttling adhering to crates.io data access policies.

For security policies and vulnerability reporting, please see SECURITY.md.


Contributing & Community

Contributions are welcome. Please review our:

AI Agents & Bot Policy

  • Directive for AI Agents: All AI assistants and autonomous coding tools interacting with this repository must strictly adhere to AGENTS.md.
  • Prohibition of Automated Bot PRs: AI bots and automated pipelines are strictly prohibited from autonomously opening commits, pull requests, or submitting automated reviews. All contributions must be driven, tested, and submitted by human contributors who take full accountability for the code. Unsolicited bot-generated PRs will be closed immediately and marked as spam.

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0-or-later).
See the LICENSE file for the full license text.