rvl

rvl

The Revelara reliability scanner.

rvl analyzes codebases for reliability risks and grounds its findings in the Revelara controls catalog and incident corpus. The scan is deterministic and makes no model calls: it resolves the API surfaces your code actually calls, matches them against a signed spec cache, and returns a blocking / advisory ladder with an exit code a git hook or CI job can gate on.

Customer code never leaves the machine. See Privacy.

Install

brew install --cask revelara-ai/tap/rvl

The cask installs rvl plus the goindex, cindex and rustindex retriever helpers beside the binary; the remaining helpers are embedded in the binary itself, so no further install step is needed.

Or download a release archive for your platform from the releases page and put its contents on your PATH.

Releases are built for macOS on Apple silicon and for Linux on x86_64 and arm64. Intel Macs get no release after 1.7.1, which stays installable from its release page.

Quick start

rvl login                  # store API credentials in ~/.revelara/config.yaml
rvl init                   # write .revelara.yaml, install the agent skills
rvl doctor                 # what is missing on this machine, for THIS repo
rvl scan                   # scan the current directory
rvl hook install           # gate `git commit` on the scan

A scan prints a finding ladder with a short id per finding:

■ BLOCKING (base severity elevated by incident evidence)
  svc/main.py:4 — requests.get has no timeout or deadline — not at the call,
  not on a client or session it is built from, and not anywhere up the call
  chain, and requests applies no default of its own; it can hang indefinitely
    severity: high
    control RC-019 · explain: rvl explain bfyx

Follow a finding from there:

rvl explain bfyx                        # the sites, the control, the fix
rvl suppress bfyx --reason="…"          # waive it in .revelara.yaml

suppress writes scanner.waivers into ./.revelara.yaml, so a waiver is a committed, reviewable decision your team shares through git rather than a setting on one laptop.

Documentation

docs/README.md maps which pages are for users and which for contributors; docs/scanning.md is the user entry point. Hosted companions: local scanning covers hooks and per-language setup in depth, and the project configuration guide covers .revelara.yaml.

Development

Build and run

make build          # cargo build
make dev            # build, then put the helpers next to the binary
make test           # cargo test --workspace
make lint           # cargo clippy --workspace --all-targets -- -D warnings
make fmt fmt-check  # cargo fmt --all [--check]
make install        # release build + helpers into $PREFIX/bin (default ~/.local/bin)
make help           # every target with its one-line description

make dev then target/debug/rvl scan <path> is the inner loop. Raw cargo still works for anything the Makefile does not wrap.

A locally built rvl scan <path> already resolves the scripted retrievers from the copies embedded in the binary, so make helpers is only needed for goindex (which cargo cannot build) and when developing a scripted helper: it copies pyindex.py / javaindex.java next to the binary, and the adjacent slot outranks the embedded one, so an edit takes effect without re-embedding. On a gvm box with a mismatched GOROOT, override the Go invocation: make helpers GO='env -u GOROOT go'.

The rule the workspace is built around

Retrievers report facts; specs carry judgment; propagation combines them mechanically. A retriever says what the code is (this call site, this client type, this method) and never whether it is a problem. What a matched surface means is spec knowledge, authored elsewhere and consumed here as data. That split is why adding a language costs compiler-frontend work and no reliability judgment, and why the scanner can ship as a binary plus a JSON cache rather than as a model. It has been violated before, and both times produced a matcher that failed its own sanity check. Do not put a verdict in a retriever.

Workspace layout

The crates under crates/, plus a helpers/ tree of retrievers that are not Rust.

helpers/ holds the out-of-process retrievers, one directory per language, each with its own README: goindex (a Go module, with its own go test suite), pyindex (Python), tsindex (Node + TypeScript), javaindex (single-file Java, JEP 330 source mode) and csindex (.NET/Roslyn, not shipped in releases). The three scripted ones are include_str!d into the binary by crates/rvl/src/embedded_helpers.rs, so editing one and rebuilding is enough to change what a release carries.

Tests and gates

CI (.github/workflows/ci.yml) runs, and a change is expected to pass all of them locally first:

cargo fmt --all --check
cargo clippy --all-targets -- -D warnings
cargo build -p rvl --bin cindex --bin rustindex   # so the C/C++ e2e runs instead of skipping
cargo test --workspace

cd helpers/goindex && go mod verify && go vet ./... && go test ./...
go run . -packet-schema                           # must print a schema version, then a content version

Two of those are worth understanding rather than just satisfying. Building cindex matters because the C/C++ end-to-end tests skip themselves when the helper is absent, and a helper the suite never builds is a lane the suite never covers. -packet-schema must be printable without loading anything, because a consumer negotiates on that number before paying for a load. Its second line, content-version, identifies the build of the helper, and the scan uses it to warn when the helper it found is not the one it ships.

CI also greps the whole tree for an internal codename and fails the build if it appears anywhere, including in comments and docs. The product is Revelara and the CLI is rvl.

The end-to-end suites in crates/rvl/tests/ are the ones most likely to catch a regression that unit tests miss, and each was written against a real failure. They run a copy of the binary in an empty directory with HOME pointed at a tempdir, because a developer machine has make helpers output next to target/debug/rvl and a populated ~/.revelara, either of which would let a test pass without the feature existing.

Where a change goes

• A new language → a retriever under helpers/ (or a crate, if it can be pure Rust), emitting packets against the rvl-core contract; then a resolution slot and a doctor lane. No reliability judgment anywhere in it.
• A new reliability judgment → the spec cache, not the code. If you find yourself hard-coding "this API is fine", you are in the wrong repository.
• A new command → crates/rvl/src/main.rs for the clap surface, with the work in the crate that owns it; platform commands live in rvl-data and owe golden-parity tests.
• A change to what --out emits → docs/out-contract.md is the contract, and orchestrators consume it. Update it in the same change.
• A change to packaging or the release flow → docs/releasing.md; dist-workspace.toml and crates/rvl/Cargo.toml both carry long comments explaining why the current shape is the way it is. Read them before simplifying either.

License

Apache-2.0. See LICENSE.