volumeleaders-rs

Disclaimer: This project is unofficial and is not affiliated with, endorsed by, or sponsored by volumeleaders.com.

Rust workspace for working with VolumeLeaders data from an authenticated browser session. The workspace has a reusable API client crate and a CLI agent crate built on top of it.

Crates

Repository layout

.
├── client/                  # Library crate
├── agent/                   # CLI crate
├── .github/workflows/       # CI, audit, release-plz, cargo-dist releases
├── AGENTS.md                # Workspace knowledge base for coding agents
├── codecov.yml              # Codecov project and patch coverage gates
├── dist-workspace.toml      # cargo-dist release artifact configuration
├── Makefile                 # Local development commands
├── cliff.toml               # Changelog grouping
├── LICENSE                  # Apache-2.0 license
└── release-plz.toml         # Release PR, crates.io publish, and tag automation

Requirements

• Rust 1.95.0 or newer
• Browser login at https://www.volumeleaders.com for commands that need live authenticated data
• Optional tools for local maintenance: cargo llvm-cov, cargo audit
• Optional tool for local patch coverage checks: diff-cover or uvx diff-cover

Development commands

make fmt
make clippy
make test
make doc
make check
make coverage
make patch-coverage
make audit

Equivalent core Cargo commands:

cargo fmt --all
cargo clippy --workspace -- -D clippy::all
cargo test --workspace
cargo doc --workspace --no-deps

CLI usage

cargo run -p volumeleaders-agent -- --help
cargo run -p volumeleaders-agent -- report list
cargo run -p volumeleaders-agent -- trade list
cargo run -p volumeleaders-agent -- completions bash

The CLI reads browser cookies automatically. If auth fails, log in to VolumeLeaders in the browser and retry. Command output goes to stdout as compact JSON by default. Pipe through jq for pretty-printed output. Errors and logs go to stderr.

trade list defaults mirror the browser /Trades/GetTrades request captured from the VolumeLeaders trades page: today's trades, 1000 requested rows, empty table search, FullTimeString24 descending order, MinVolume=10000, MaxVolume=2000000000, MinPrice=0, MaxPrice=100000, MinDollars=500000, MaxDollars=100000000000, Conditions=0, VCD=0, SecurityTypeKey=-1, RelativeSize=0, DarkPools=-1, Sweeps=-1, LatePrints=-1, SignaturePrints=-1, EvenShared=-1, TradeRank=100, TradeRankSnapshot=-1, MarketCap=0, and all session toggles enabled. Pass date, range, or filter flags to override those browser defaults.

Trade-shaped outputs intentionally omit the upstream PercentDailyVolume field. Live report data returns that value as 0.0 for current and prior trading days, so returning it would suggest a meaningful percentage where the source data does not provide one. Compact defaults also omit TradeConditions, RelativeSize, Name, and Volume on trade-shaped rows to avoid surfacing fields that are consistently null or misleadingly sparse in those surfaces. RelativeSize remains in full output and is still surfaced in level-centric data when requested.

Client example

cargo run -p volumeleaders-client --example rookie_spike

The rookie_spike example checks whether required VolumeLeaders cookies can be extracted from Chrome, then Firefox, and prints manual fallback guidance if needed.

Tests and fixtures

• Most tests are inline #[cfg(test)] modules in client/src/** and agent/src/**.
• Client fixtures live in client/tests/fixtures/*.json and represent server payload contracts.
• Client HTTP tests use mockito.
• make coverage and CI enforce 90 percent workspace line coverage with cargo llvm-cov; Codecov also requires 90 percent project coverage and 100 percent patch coverage for changed lines.
• Run make patch-coverage before opening a PR to generate lcov.info and check changed-line coverage against main. Override the base branch with PATCH_COVERAGE_BASE=<branch> or use DIFF_COVER='uvx diff-cover' if diff-cover is not installed as a standalone command.
• There are no standalone Rust integration test files or benchmarks today.

Release automation

• cd.yml runs release-plz on pushes to main and on manual dispatch. It uses the RELEASE_PLZ_TOKEN secret so release PR branch updates and release tags can trigger normal GitHub Actions workflows.
• release-plz.toml keeps the changelog current, opens release PRs, publishes publishable workspace crates to crates.io, and creates git tags. GitHub Releases are disabled there because cargo-dist owns artifact releases.
• dist-workspace.toml configures cargo-dist for the volumeleaders-agent binary installers and generated GitHub Release workflow.
• The cargo-dist release workflow updates Rust to the current stable toolchain before artifact builds so runner image defaults do not fall below the workspace MSRV.
• The first crates.io release for each crate must be published manually with a crates.io API token. After that, configure crates.io Trusted Publishing for major/volumeleaders-rs with workflow file cd.yml; release-plz can then publish through GitHub OIDC without storing a CARGO_REGISTRY_TOKEN secret.
• Publish workspace crates in dependency order: volumeleaders-client first, then volumeleaders-agent after the client version is available in the crates.io index.

Documentation freshness

Keep README.md and relevant AGENTS.md files updated in the same change as code. Update docs when commands, public APIs, auth/session behavior, fixtures, CI, release flow, or project layout change. Inaccurate docs are worse than no docs.