cargo-unmaintained

Crates.iocargo-unmaintained
lib.rscargo-unmaintained
version1.0.2
sourcesrc
created_at2023-11-10 21:55:17.478179
updated_at2024-05-24 20:18:34.754707
descriptionFind unmaintained packages in Rust projects
homepage
repositoryhttps://github.com/trailofbits/cargo-unmaintained
max_upload_size
id1031485
size433,336
Samuel Moelius (smoelius)

documentation

README

cargo-unmaintained

Find unmaintained packages in Rust projects

cargo-unmaintained is similar to cargo-audit. However, cargo-unmaintained finds unmaintained packages automatically using heuristics, rather than rely on users to manually submit them to the RustSec Advisory Database.

cargo-unmaintained defines an unmaintained package X as one that satisfies one of 1 through 3 below:

  1. X's repository is archived (see Notes below).

  2. X is not a member of its named repository.

  3. Both a and b below.

    a. X depends on a version of a package Y that is incompatible with the Y's latest version.

    b. Either X has no associated repository, or its repository's last commit was over a year ago (a configurable value).

As of 2024-04-28, the RustSec Advisory Database contains 98 active advisories for unmaintained packages. Using the above conditions, cargo-unmaintained automatically identifies 70 of them (more than two thirds). These results can be reproduced by running the rustsec_advisories binary within this repository.

Notes

  • To check whether packages' repositories have been archived, set the GITHUB_TOKEN_PATH environment variable to the path of a file containing a personal access token. If unset, this check will be skipped.

  • The above conditions consider a "leaf" package (i.e., a package with no dependencies) unmaintained only if conditions 1 or 2 apply.

  • The purpose of condition 3(b) is to give package maintainers a chance to update their packages. That is, an incompatible upgrade to one of X's dependencies could require time-consuming changes to X. Without this check, cargo-unmaintained would produce many false positives.

  • Of the 28 packages in the RustSec Advisory Database not identified by cargo-unmaintained:

    • 8 do not build
    • 3 are existent, unarchived leaves
    • 2 were updated within the past 365 days
    • 15 were not identified for other reasons

Output

cargo-unmaintained's output includes the number of days since a package's repository was last updated, along with the dependencies that cause the package to be considered unmaintained.

For example, the following is the output produced by running cargo-unmaintained on Cargo 0.74.0 on 2023-11-11:

Installation

cargo install cargo-unmaintained

Usage

Usage: cargo unmaintained [OPTIONS]

Options:
      --color <WHEN>    When to use color: always, auto, or never [default: auto]
      --fail-fast       Exit as soon as an unmaintained package is found
      --max-age <DAYS>  Age in days that a repository's last commit must not exceed for the
                        repository to be considered current; 0 effectively disables this check,
                        though ages are still reported [default: 365]
      --no-cache        Do not save cloned repositories on disk for future runs
      --no-exit-code    Do not set exit status when unmaintained packages are found
      --no-warnings     Do not show warnings
  -p, --package <NAME>  Check only whether package NAME is unmaintained
      --tree            Show paths to unmaintained packages
      --verbose         Show information about what cargo-unmaintained is doing
  -h, --help            Print help
  -V, --version         Print version

The `GITHUB_TOKEN_PATH` environment variable can be set to the path of a file containing a personal
access token. If set, cargo-unmaintained will use this token to authenticate to GitHub and check
whether packages' repositories have been archived.

Unless --no-exit-code is passed, the exit status is 0 if no unmaintained packages were found and no
irrecoverable errors occurred, 1 if unmaintained packages were found, and 2 if an irrecoverable
error occurred.

Ignoring packages

If a workspace's Cargo.toml file includes a workspace.metadata.unmaintained.ignore array, all packages named therein will be ignored. Example:

[workspace.metadata.unmaintained]
ignore = ["matchers"]

Testing

Some tests are not run by default because they are "externally influenced," i.e., they rely on data from external sources. To enable these additional tests, enable feature test-ei, e.g.:

cargo test --features=test-ei

Known problems

Repositories whose urls change across versions may be incorrectly reported as unmaintained. cargo-unmaintained treats the metadata of the latest version of a package referred to by a project as "ground truth." However, this can cause false positives. For example, if the latest version of regex-automata that your project relies on is 0.2.0, cargo-unmaintained will report the package is unmaintained, though it is not.

License

cargo-unmaintained is licensed and distributed under the AGPLv3 license. Contact us if you're looking for an exception to the terms.

Commit count: 427

cargo fmt