**Head's up!**: Lift is under early development,
and many or all of the features described in this
document aren't implemented...yet!

A tool for hosting, auditing, and mirroring
[`cargo`](https://doc.rust-lang.org/cargo/) Crates
from [`crates.io`](https://www.crates.io).

## Usage: Auditing Crates

Lift combines several linting and auditing tools into one 
command (`cargo lift check`):

- [`cargo fmt --check`](https://github.com/rust-lang/rustfmt) (_Local Only_),
  which checks your code for formatting discrepancies.

- [`cargo clippy`](https://github.com/rust-lang/rust-clippy) (_Local Only_), 
  which checks your code for "smells", simple mistakes,
  and maintainability issues.

- [`cargo geiger`](https://github.com/rust-secure-code/cargo-geiger) (_Local Only_),
  which checks your code for usage of the `unsafe` keyword.

- [`cargo audit`](https://github.com/RustSec/rustsec/tree/main/cargo-audit),
  which checks for security advisories related to a Crate or its dependencies via the
  [RustSec Advisory Database](https://github.com/RustSec/advisory-db).

- [`cargo vet`](https://github.com/mozilla/cargo-vet) or
  [`cargo crev`](https://github.com/crev-dev/cargo-crev),
  which check for _failing_ audits related to a Crate or its dependencies via
  a distributed set of human-certified code reviews.

### Auditing a Local `Cargo.toml`

To audit a local Crate or [Workspace](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html)
containing a `Cargo.toml` file, run:

```sh
cargo lift check
```

To skip auditing non-Workspace dependencies 
of the `Cargo.toml` file (e.g., all 3rd-party code), run:

```sh
cargo lift check --relaxed
```

When the command exits, Lift will print a report
flagging any checks that failed for the `Cargo.toml`
(and its dependencies, if not `--relaxed`).

## Usage: Mirroring `crates.io`

Lift can download and host ("mirror") copies
of any Crate hosted on [`crates.io`](https://www.crates.io).

### Mirroring Every Crate from `crates.io`

> _Warning_: Although Lift doesn't download
> _every_ version of _every_ Crate from `crates.io`
> (by default), it will still download _many_
> Crates. This mirroring operation can easily
> eat up all your network bandwidth _and_ disk space!

To mirror the _entire_ `crates.io` index, run:

```sh
cargo lift mirror * --from crates.io
```

Each mirrored Crate will be available in the
local Lift repository after this command exits.

#### How Mirrored Versions are Selected

For each Crate, only one version is guaranteed
to be mirrored. When selecting this version,
Lift will:

1. Prefer versions which would pass the
   `cargo lift check --relaxed` command.
2. Prefer versions which _aren't_ yanked.
3. Prefer the highest ("latest") version.

Lift will mirror additional versions of a Crate
if they are required to satify direct or indirect
("**transitive**") dependencies of another Crate.

By default, Lift will ignore _any_ Crates which
would fail to pass the `cargo lift check --relaxed`
command, unless those Crates are required to satisfy
a transitive dependency in another Crate.

### Mirroring One Crate from `crates.io`

To mirror a _specific_ Crate, and all of it's direct
and indirect dependencies, from `crates.io`, run:

```sh
cargo lift mirror tokio@1.29.1 --from crates.io
```

In this example, version `1.29.1` of the `tokio`
crate would be mirrored from `crates.io`, along
with each of its transitive dependencies.

The `mirror` sub-command accepts _any_ version string
that would normally be used in a `Cargo-toml`. For
example, `*` could be used instead of `1.29.1` in the 
example above, causing Lift to select a version
automatically.

## License and Contributions Notice

Except where otherwise noted, this project is 
Copyright (C) 2023 Brandon Sanders [hello@crahda.cc],
and licensed under the [AGPL-3.0-only](LICENSE.txt).

When submitting a contribution to this repository, you
grant the copyright holder(s) of this repository a 
non-exclusive, worldwide, royalty-free license to make,
use, sell, offer for sale, import and otherwise run, modify,
and propagate the contents of your "contributor version",
as defined in section 11 of the `AGPL-3.0-only` license.