From 4bd8203af155f2804da0fadc7522a1923808e0b7 Mon Sep 17 00:00:00 2001 From: Aria Beingessner Date: Fri, 26 Aug 2022 22:41:38 -0400 Subject: [PATCH 1/3] TEST: update to clap 4.0.0-prerelease --- Cargo.lock | 46 ++- Cargo.toml | 2 +- src/cli.rs | 53 ++- tests/snapshots/test_cli__long-help.snap | 66 +-- tests/snapshots/test_cli__markdown-help.snap | 414 +++++++++++++------ tests/snapshots/test_cli__short-help.snap | 38 +- tests/test-cli.rs | 2 +- 7 files changed, 428 insertions(+), 193 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 579b6962..5e968ffc 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -114,7 +114,7 @@ name = "cargo-vet" version = "0.3.0" dependencies = [ "cargo_metadata", - "clap", + "clap 4.0.0-alpha.0", "clap-cargo", "console", "crates-index", @@ -181,15 +181,25 @@ version = "3.2.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9f1fe12880bae935d142c8702d500c63a4e8634b6c3c57ad72bf978fc7b6249a" dependencies = [ - "atty", "bitflags", - "clap_derive", - "clap_lex", + "clap_derive 3.2.6", + "clap_lex 0.2.2", "indexmap", "once_cell", + "textwrap", +] + +[[package]] +name = "clap" +version = "4.0.0-alpha.0" +source = "git+https://github.com/clap-rs/clap#a2f3ee2cfa3767ed6ddd6c8c27ec154ef3f8a890" +dependencies = [ + "atty", + "bitflags", + "clap_derive 4.0.0-alpha.0", + "clap_lex 0.2.4", "strsim", "termcolor", - "textwrap", ] [[package]] @@ -198,7 +208,7 @@ version = "0.9.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "841b17c26cdae63b80cd9014f4fb779b761c388908bdf58e15223a08d65e9b08" dependencies = [ - "clap", + "clap 3.2.6", "doc-comment", ] @@ -215,6 +225,18 @@ dependencies = [ "syn", ] +[[package]] +name = "clap_derive" +version = "4.0.0-alpha.0" +source = "git+https://github.com/clap-rs/clap#a2f3ee2cfa3767ed6ddd6c8c27ec154ef3f8a890" +dependencies = [ + "heck", + "proc-macro-error", + "proc-macro2", + "quote", + "syn", +] + [[package]] name = "clap_lex" version = "0.2.2" @@ -224,6 +246,14 @@ dependencies = [ "os_str_bytes", ] +[[package]] +name = "clap_lex" +version = "0.2.4" +source = "git+https://github.com/clap-rs/clap#a2f3ee2cfa3767ed6ddd6c8c27ec154ef3f8a890" +dependencies = [ + "os_str_bytes", +] + [[package]] name = "combine" version = "4.6.4" @@ -917,9 +947,9 @@ dependencies = [ [[package]] name = "proc-macro2" -version = "1.0.39" +version = "1.0.43" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c54b25569025b7fc9651de43004ae593a75ad88543b17178aa5e1b9c4f15f56f" +checksum = "0a2ca2c61bc9f3d74d2886294ab7b9853abd9c1ad903a3ac7815c58989bb7bab" dependencies = [ "unicode-ident", ] diff --git a/Cargo.toml b/Cargo.toml index 92d72c65..49d18eea 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -18,7 +18,7 @@ exclude = [ [dependencies] cargo_metadata = "0.14.2" -clap = { version = "3.2.6", features = ["derive"] } +clap = { git="https://github.com/clap-rs/clap", features = ["derive"] } clap-cargo = "0.9.1" console = "0.15.0" crates-index = { version = "0.18.8", default-features = false } diff --git a/src/cli.rs b/src/cli.rs index f19d89dd..cbfdd819 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -18,7 +18,6 @@ pub enum FakeCli { #[clap(version)] #[clap(bin_name = "cargo vet")] #[clap(args_conflicts_with_subcommands = true)] -#[clap(global_setting(clap::AppSettings::DeriveDisplayOrder))] /// Supply-chain security for Rust /// /// When run without a subcommand, `cargo vet` will invoke the `check` @@ -30,7 +29,7 @@ pub struct Cli { // Top-level flags /// Path to Cargo.toml - #[clap(long, name = "PATH", parse(from_os_str))] + #[clap(long, name = "PATH", value_parser)] #[clap(help_heading = "GLOBAL OPTIONS", global = true)] pub manifest_path: Option, @@ -48,7 +47,7 @@ pub struct Cli { pub no_default_features: bool, /// Space-separated list of features to activate - #[clap(long, action, require_value_delimiter = true, value_delimiter = ' ')] + #[clap(long, action, value_delimiter = ' ')] #[clap(help_heading = "GLOBAL OPTIONS", global = true)] pub features: Vec, @@ -73,7 +72,7 @@ pub struct Cli { /// How verbose logging should be (log level) #[clap(long, action)] #[clap(default_value_t = LevelFilter::WARN)] - #[clap(possible_values = ["off", "error", "warn", "info", "debug", "trace"])] + #[clap(value_parser = verbose_value_parser(["off", "error", "warn", "info", "debug", "trace"]))] #[clap(help_heading = "GLOBAL OPTIONS", global = true)] pub verbose: LevelFilter, @@ -158,6 +157,52 @@ pub struct Cli { pub check_args: CheckArgs, } +fn verbose_value_parser(values: impl IntoIterator) -> VerboseValuesParser { + VerboseValuesParser(values.into_iter().collect()) +} + +#[derive(Clone, Debug)] +pub struct VerboseValuesParser(Vec<&'static str>); + +impl clap::builder::TypedValueParser for VerboseValuesParser { + type Value = LevelFilter; + + fn parse_ref( + &self, + cmd: &clap::Command, + arg: Option<&clap::Arg>, + value: &std::ffi::OsStr, + ) -> Result { + clap::builder::TypedValueParser::parse(self, cmd, arg, value.to_owned()) + } + + fn parse( + &self, + _cmd: &clap::Command, + _arg: Option<&clap::Arg>, + value: std::ffi::OsString, + ) -> Result { + let value = value + .into_string() + .map_err(|_| clap::Error::raw(clap::error::ErrorKind::InvalidUtf8, "invalid utf8"))?; + + value.parse().map_err(|_e| { + clap::Error::raw( + clap::error::ErrorKind::InvalidValue, + format!("must be one of {:?}", self.0), + ) + }) + } + + fn possible_values( + &self, + ) -> Option + '_>> { + Some(Box::new( + self.0.iter().map(|s| clap::builder::PossibleValue::from(s)), + )) + } +} + #[derive(Subcommand)] pub enum Commands { // Main commands: diff --git a/tests/snapshots/test_cli__long-help.snap b/tests/snapshots/test_cli__long-help.snap index ba5d45a7..b86aec72 100644 --- a/tests/snapshots/test_cli__long-help.snap +++ b/tests/snapshots/test_cli__long-help.snap @@ -3,17 +3,47 @@ source: tests/test-cli.rs expression: format_outputs(&output) --- stdout: -cargo-vet 0.3.0 +cargo-vet-vet 0.3.0 Supply-chain security for Rust When run without a subcommand, `cargo vet` will invoke the `check` subcommand. See `cargo vet help check` for more details. -USAGE: +Usage: cargo vet [OPTIONS] cargo vet -OPTIONS: +Subcommands: + check + \[default\] Check that the current project has been vetted + suggest + Suggest some low-hanging fruit to review + init + Initialize cargo-vet for your project + inspect + Fetch the source of a package + diff + Yield a diff against the last reviewed version + certify + Mark a package as audited + regenerate + Explicitly regenerate various pieces of information + add-exemption + Mark a package as exempted from review + record-violation + Declare that some versions of a package violate certain audit criteria + fmt + Reformat all of vet's files (in case you hand-edited them) + fetch-imports + Explicitly fetch the imports (foreign audit files) + dump-graph + Print the cargo build graph as understood by `cargo vet` + gc + Clean up old packages from the vet cache + help + Print this message or the help of the given subcommand(s) + +Options: --shallow Avoid suggesting audits for dependencies of unaudited dependencies. @@ -126,35 +156,5 @@ GLOBAL OPTIONS: * `is_dev_only($bool)`: whether it's only used by dev (test) builds in the original graph -SUBCOMMANDS: - check - \[default\] Check that the current project has been vetted - suggest - Suggest some low-hanging fruit to review - init - Initialize cargo-vet for your project - inspect - Fetch the source of a package - diff - Yield a diff against the last reviewed version - certify - Mark a package as audited - regenerate - Explicitly regenerate various pieces of information - add-exemption - Mark a package as exempted from review - record-violation - Declare that some versions of a package violate certain audit criteria - fmt - Reformat all of vet's files (in case you hand-edited them) - fetch-imports - Explicitly fetch the imports (foreign audit files) - dump-graph - Print the cargo build graph as understood by `cargo vet` - gc - Clean up old packages from the vet cache - help - Print this message or the help of the given subcommand(s) - stderr: diff --git a/tests/snapshots/test_cli__markdown-help.snap b/tests/snapshots/test_cli__markdown-help.snap index 45b9d7a0..21be1acc 100644 --- a/tests/snapshots/test_cli__markdown-help.snap +++ b/tests/snapshots/test_cli__markdown-help.snap @@ -7,22 +7,48 @@ stdout: > This manual can be regenerated with `cargo vet help-markdown` -Version: `cargo-vet 0.3.0` +Version: `vet 0.3.0` Supply-chain security for Rust When run without a subcommand, `cargo vet` will invoke the `check` subcommand. See `cargo vet help check` for more details. -### USAGE -``` +### Usage cargo vet [OPTIONS] -``` -``` cargo vet -``` -### OPTIONS +### Subcommands +check +\[default\] Check that the current project has been vetted +suggest +Suggest some low-hanging fruit to review +init +Initialize cargo-vet for your project +inspect +Fetch the source of a package +diff +Yield a diff against the last reviewed version +certify +Mark a package as audited +regenerate +Explicitly regenerate various pieces of information +add-exemption +Mark a package as exempted from review +record-violation +Declare that some versions of a package violate certain audit criteria +fmt +Reformat all of vet's files (in case you hand-edited them) +fetch-imports +Explicitly fetch the imports (foreign audit files) +dump-graph +Print the cargo build graph as understood by `cargo vet` +gc +Clean up old packages from the vet cache +help +Print this message or the help of the given subcommand(s) + +### Options #### `--shallow` Avoid suggesting audits for dependencies of unaudited dependencies. @@ -135,22 +161,6 @@ tested) * `is_dev_only($bool)`: whether it's only used by dev (test) builds in the original graph -### SUBCOMMANDS -* [check](#cargo-vet-check): \[default\] Check that the current project has been vetted -* [suggest](#cargo-vet-suggest): Suggest some low-hanging fruit to review -* [init](#cargo-vet-init): Initialize cargo-vet for your project -* [inspect](#cargo-vet-inspect): Fetch the source of a package -* [diff](#cargo-vet-diff): Yield a diff against the last reviewed version -* [certify](#cargo-vet-certify): Mark a package as audited -* [regenerate](#cargo-vet-regenerate): Explicitly regenerate various pieces of information -* [add-exemption](#cargo-vet-add-exemption): Mark a package as exempted from review -* [record-violation](#cargo-vet-record-violation): Declare that some versions of a package violate certain audit criteria -* [fmt](#cargo-vet-fmt): Reformat all of vet's files (in case you hand-edited them) -* [fetch-imports](#cargo-vet-fetch-imports): Explicitly fetch the imports (foreign audit files) -* [dump-graph](#cargo-vet-dump-graph): Print the cargo build graph as understood by `cargo vet` -* [gc](#cargo-vet-gc): Clean up old packages from the vet cache -* [help](#cargo-vet-help): Print this message or the help of the given subcommand(s) -


## cargo vet check \[default\] Check that the current project has been vetted @@ -161,15 +171,15 @@ If the check fails due to lack of audits, we will do our best to explain why vet what should be done to fix it. This can involve a certain amount of guesswork, as there are many possible solutions and we only want to recommend the "best" one to keep things simple. -Failures and suggestions can either be "Certain" or "Speculative". Speculative items are greyed -out and sorted lower to indicate that the Certain entries should be looked at first. Speculative -items are for packages that probably need audits too, but only appear as transitive dependencies of +Failures and suggestions can either be "Certain" or "Speculative". Speculative items are greyed out +and sorted lower to indicate that the Certain entries should be looked at first. Speculative items +are for packages that probably need audits too, but only appear as transitive dependencies of Certain items. During review of Certain issues you may take various actions that change what's needed for the -Speculative ones. For instance you may discover you're enabling a feature you don't need, and -that's the only reason the Speculative package is in your tree. Or you may determine that the -Certain package only needs to be safe-to-run, which may make the Speculative requirements weaker or +Speculative ones. For instance you may discover you're enabling a feature you don't need, and that's +the only reason the Speculative package is in your tree. Or you may determine that the Certain +package only needs to be safe-to-run, which may make the Speculative requirements weaker or completely resolved. For these reasons we recommend fixing problems "top down", and Certain items are The Top. @@ -183,12 +193,10 @@ exemptions necessary to make `check` pass (and remove uneeded ones). Ideally you this and prefer adding audits, but if you've done all the audits you plan on doing, that's the way to finish the job. -### USAGE -``` +### Usage cargo vet check [OPTIONS] -``` -### OPTIONS +### Options #### `--shallow` Avoid suggesting audits for dependencies of unaudited dependencies. @@ -216,12 +224,10 @@ remove it while suggesting. See also `regenerate exemptions`, which can be used to "garbage collect" your backlog (if you run it while `check` is passing). -### USAGE -``` +### Usage cargo vet suggest [OPTIONS] -``` -### OPTIONS +### Options #### `--shallow` Avoid suggesting audits for dependencies of unaudited dependencies. @@ -245,12 +251,10 @@ This will add `exemptions` and `audit-as-crates-io = false` for all packages tha At this point you can either configure your project further or start working on your review backlog with `suggest`. -### USAGE -``` +### Usage cargo vet init [OPTIONS] -``` -### OPTIONS +### Options #### `-h, --help` Print help information @@ -261,22 +265,20 @@ This subcommand accepts all the [global options](#global-options) ## cargo vet inspect Fetch the source of a package -We will attempt to guess what criteria you want to audit the package for based on the current check/ -suggest status, and show you the meaning of those criteria ahead of time. +We will attempt to guess what criteria you want to audit the package for based on the current +check/suggest status, and show you the meaning of those criteria ahead of time. -### USAGE -``` +### Usage cargo vet inspect [OPTIONS] -``` -### ARGS +### Arguments #### `` The package to inspect #### `` The version to inspect -### OPTIONS +### Options #### `--mode ` How to inspect the source @@ -293,15 +295,13 @@ This subcommand accepts all the [global options](#global-options) ## cargo vet diff Yield a diff against the last reviewed version -We will attempt to guess what criteria you want to audit the package for based on the current check/ -suggest status, and show you the meaning of those criteria ahead of time. +We will attempt to guess what criteria you want to audit the package for based on the current +check/suggest status, and show you the meaning of those criteria ahead of time. -### USAGE -``` +### Usage cargo vet diff [OPTIONS] -``` -### ARGS +### Arguments #### `` The package to diff @@ -311,7 +311,7 @@ The base version to diff #### `` The target version to diff -### OPTIONS +### Options #### `--mode ` How to inspect the source @@ -341,12 +341,10 @@ on your backlog and instead use the recommendations of `suggest`. If this removes the need for an `exemption` will we automatically remove it. -### USAGE -``` +### Usage cargo vet certify [OPTIONS] [ARGS] -``` -### ARGS +### Arguments #### `` The package to certify as audited @@ -356,7 +354,7 @@ The version to certify as audited #### `` If present, instead certify a diff from version1->version2 -### OPTIONS +### Options #### `--criteria ` The criteria to certify for this audit @@ -402,22 +400,25 @@ automatic if we agree they're boring/reliable enough. See the subcommands for specifics. -### USAGE -``` +### Usage cargo vet regenerate [OPTIONS] -``` -### OPTIONS +### Subcommands +exemptions +Regenerate your exemptions to make `check` pass minimally +imports +Regenerate your imports and accept changes to criteria +audit-as-crates-io +Regenerate you audit-as-crates-io entries to make `check` pass +help +Print this message or the help of the given subcommand(s) + +### Options #### `-h, --help` Print help information ### GLOBAL OPTIONS This subcommand accepts all the [global options](#global-options) -### SUBCOMMANDS -* [exemptions](#cargo-vet-exemptions): Regenerate your exemptions to make `check` pass minimally -* [imports](#cargo-vet-imports): Regenerate your imports and accept changes to criteria -* [audit-as-crates-io](#cargo-vet-audit-as-crates-io): Regenerate you audit-as-crates-io entries to make `check` pass -* [help](#cargo-vet-help): Print this message or the help of the given subcommand(s)


## cargo vet exemptions @@ -427,16 +428,14 @@ This command can be used for two purposes: to force your supply-chain to pass `c currently failing, or to minimize/garbage-collect your exemptions when it's already passing. These are ultimately the same operation. -We will try our best to preserve existing exemptions, removing only those that aren't needed, -and adding only those that are needed. Exemptions that are overbroad may also be weakened (i.e. +We will try our best to preserve existing exemptions, removing only those that aren't needed, and +adding only those that are needed. Exemptions that are overbroad may also be weakened (i.e. safe-to-deploy may be reduced to safe-to-run). -### USAGE -``` +### Usage cargo vet regenerate exemptions [OPTIONS] -``` -### OPTIONS +### Options #### `-h, --help` Print help information @@ -450,12 +449,10 @@ Regenerate your imports and accept changes to criteria This is equivalent to `cargo vet fetch-imports` but it won't produce an error if the descriptions of foreign criteria change. -### USAGE -``` +### Usage cargo vet regenerate imports [OPTIONS] -``` -### OPTIONS +### Options #### `-h, --help` Print help information @@ -468,12 +465,10 @@ Regenerate you audit-as-crates-io entries to make `check` pass This will just set any problematic entries to `audit-as-crates-io = false`. -### USAGE -``` +### Usage cargo vet regenerate audit-as-crates-io [OPTIONS] -``` -### OPTIONS +### Options #### `-h, --help` Print help information @@ -484,17 +479,46 @@ This subcommand accepts all the [global options](#global-options) ## cargo vet help Print this message or the help of the given subcommand(s) -### USAGE -``` -cargo vet regenerate help [OPTIONS] [SUBCOMMAND]... -``` +### Usage +cargo vet regenerate help [SUBCOMMAND] -### ARGS -#### `...` -The subcommand whose help message to display +### Subcommands +exemptions +Regenerate your exemptions to make `check` pass minimally +imports +Regenerate your imports and accept changes to criteria +audit-as-crates-io +Regenerate you audit-as-crates-io entries to make `check` pass +help +Print this message or the help of the given subcommand(s) -### GLOBAL OPTIONS -This subcommand accepts all the [global options](#global-options) +


+## cargo vet exemptions +Regenerate your exemptions to make `check` pass minimally + +### Usage +cargo vet regenerate help exemptions + +


+## cargo vet imports +Regenerate your imports and accept changes to criteria + +### Usage +cargo vet regenerate help imports + +


+## cargo vet audit-as-crates-io +Regenerate you audit-as-crates-io entries to make `check` pass + +### Usage +cargo vet regenerate help audit-as-crates-io + +


+## cargo vet help +Print this message or the help of the given subcommand(s) + +### Usage +cargo vet regenerate help help


## cargo vet add-exemption @@ -508,19 +532,17 @@ necessary to make progress. unnecessary ones), so we recommend using that over `add-exemption`. This command mostly exists as "plumbing" for building tools on top of `cargo vet`. -### USAGE -``` +### Usage cargo vet add-exemption [OPTIONS] -``` -### ARGS +### Arguments #### `` The package to mark as exempted #### `` The version to mark as exempted -### OPTIONS +### Options #### `--criteria ` The criteria to assume (trust) @@ -576,19 +598,17 @@ When a violation *does* cause an integrity error, it's up to you and your peers to do about it. There isn't yet a mechanism for dealing with disagreements with a peer's published violations. -### USAGE -``` +### Usage cargo vet record-violation [OPTIONS] -``` -### ARGS +### Arguments #### `` The package to forbid #### `` The versions to forbid -### OPTIONS +### Options #### `--criteria ` The criteria that have failed to be satisfied. @@ -623,12 +643,10 @@ Reformat all of vet's files (in case you hand-edited them) Most commands will implicitly do this, so this mostly exists as "plumbing" for building tools on top of vet, or in case you don't want to run another command. -### USAGE -``` +### Usage cargo vet fmt [OPTIONS] -``` -### OPTIONS +### Options #### `-h, --help` Print help information @@ -642,12 +660,10 @@ Explicitly fetch the imports (foreign audit files) `cargo vet check` will implicitly do this, so this mostly exists as "plumbing" for building tools on top of vet. -### USAGE -``` +### Usage cargo vet fetch-imports [OPTIONS] -``` -### OPTIONS +### Options #### `-h, --help` Print help information @@ -672,12 +688,10 @@ applied *before* doing any semantic analysis, so if you filter out a package and the problem will disappear. This can be used to bisect a problem if you get ambitious enough with your filters. -### USAGE -``` +### Usage cargo vet dump-graph [OPTIONS] -``` -### OPTIONS +### Options #### `--depth ` The depth of the graph to print (for a large project, the full graph is a HUGE MESS) @@ -699,12 +713,10 @@ recognized by cargo-vet. In the future, many cargo-vet subcommands will implicitly do this. -### USAGE -``` +### Usage cargo vet gc [OPTIONS] -``` -### OPTIONS +### Options #### `--max-package-age-days ` Packages in the vet cache which haven't been used for this many days will be removed @@ -724,17 +736,165 @@ This subcommand accepts all the [global options](#global-options) ## cargo vet help Print this message or the help of the given subcommand(s) -### USAGE -``` -cargo vet help [OPTIONS] [SUBCOMMAND]... -``` +### Usage +cargo vet help [SUBCOMMAND] + +### Subcommands +check +\[default\] Check that the current project has been vetted +suggest +Suggest some low-hanging fruit to review +init +Initialize cargo-vet for your project +inspect +Fetch the source of a package +diff +Yield a diff against the last reviewed version +certify +Mark a package as audited +regenerate +Explicitly regenerate various pieces of information +add-exemption +Mark a package as exempted from review +record-violation +Declare that some versions of a package violate certain audit criteria +fmt +Reformat all of vet's files (in case you hand-edited them) +fetch-imports +Explicitly fetch the imports (foreign audit files) +dump-graph +Print the cargo build graph as understood by `cargo vet` +gc +Clean up old packages from the vet cache +help +Print this message or the help of the given subcommand(s) + +


+## cargo vet check +\[default\] Check that the current project has been vetted -### ARGS -#### `...` -The subcommand whose help message to display +### Usage +cargo vet help check -### GLOBAL OPTIONS -This subcommand accepts all the [global options](#global-options) +


+## cargo vet suggest +Suggest some low-hanging fruit to review + +### Usage +cargo vet help suggest + +


+## cargo vet init +Initialize cargo-vet for your project + +### Usage +cargo vet help init + +


+## cargo vet inspect +Fetch the source of a package + +### Usage +cargo vet help inspect + +


+## cargo vet diff +Yield a diff against the last reviewed version + +### Usage +cargo vet help diff + +


+## cargo vet certify +Mark a package as audited + +### Usage +cargo vet help certify + +


+## cargo vet regenerate +Explicitly regenerate various pieces of information + +### Usage +cargo vet help regenerate [SUBCOMMAND] + +### Subcommands +exemptions +Regenerate your exemptions to make `check` pass minimally +imports +Regenerate your imports and accept changes to criteria +audit-as-crates-io +Regenerate you audit-as-crates-io entries to make `check` pass + +


+## cargo vet exemptions +Regenerate your exemptions to make `check` pass minimally + +### Usage +cargo vet help regenerate exemptions + +


+## cargo vet imports +Regenerate your imports and accept changes to criteria + +### Usage +cargo vet help regenerate imports + +


+## cargo vet audit-as-crates-io +Regenerate you audit-as-crates-io entries to make `check` pass + +### Usage +cargo vet help regenerate audit-as-crates-io + +


+## cargo vet add-exemption +Mark a package as exempted from review + +### Usage +cargo vet help add-exemption + +


+## cargo vet record-violation +Declare that some versions of a package violate certain audit criteria + +### Usage +cargo vet help record-violation + +


+## cargo vet fmt +Reformat all of vet's files (in case you hand-edited them) + +### Usage +cargo vet help fmt + +


+## cargo vet fetch-imports +Explicitly fetch the imports (foreign audit files) + +### Usage +cargo vet help fetch-imports + +


+## cargo vet dump-graph +Print the cargo build graph as understood by `cargo vet` + +### Usage +cargo vet help dump-graph + +


+## cargo vet gc +Clean up old packages from the vet cache + +### Usage +cargo vet help gc + +


+## cargo vet help +Print this message or the help of the given subcommand(s) + +### Usage +cargo vet help help stderr: diff --git a/tests/snapshots/test_cli__short-help.snap b/tests/snapshots/test_cli__short-help.snap index 80e28819..25456bca 100644 --- a/tests/snapshots/test_cli__short-help.snap +++ b/tests/snapshots/test_cli__short-help.snap @@ -3,14 +3,30 @@ source: tests/test-cli.rs expression: format_outputs(&output) --- stdout: -cargo-vet 0.3.0 +cargo-vet-vet 0.3.0 Supply-chain security for Rust -USAGE: +Usage: cargo vet [OPTIONS] cargo vet -OPTIONS: +Subcommands: + check \[default\] Check that the current project has been vetted + suggest Suggest some low-hanging fruit to review + init Initialize cargo-vet for your project + inspect Fetch the source of a package + diff Yield a diff against the last reviewed version + certify Mark a package as audited + regenerate Explicitly regenerate various pieces of information + add-exemption Mark a package as exempted from review + record-violation Declare that some versions of a package violate certain audit criteria + fmt Reformat all of vet's files (in case you hand-edited them) + fetch-imports Explicitly fetch the imports (foreign audit files) + dump-graph Print the cargo build graph as understood by `cargo vet` + gc Clean up old packages from the vet cache + help Print this message or the help of the given subcommand(s) + +Options: --shallow Avoid suggesting audits for dependencies of unaudited dependencies -h, --help Print help information -V, --version Print version information @@ -58,21 +74,5 @@ GLOBAL OPTIONS: --filter-graph Filter out different parts of the build graph and pretend that's the true graph -SUBCOMMANDS: - check \[default\] Check that the current project has been vetted - suggest Suggest some low-hanging fruit to review - init Initialize cargo-vet for your project - inspect Fetch the source of a package - diff Yield a diff against the last reviewed version - certify Mark a package as audited - regenerate Explicitly regenerate various pieces of information - add-exemption Mark a package as exempted from review - record-violation Declare that some versions of a package violate certain audit criteria - fmt Reformat all of vet's files (in case you hand-edited them) - fetch-imports Explicitly fetch the imports (foreign audit files) - dump-graph Print the cargo build graph as understood by `cargo vet` - gc Clean up old packages from the vet cache - help Print this message or the help of the given subcommand(s) - stderr: diff --git a/tests/test-cli.rs b/tests/test-cli.rs index e546579e..83bae217 100644 --- a/tests/test-cli.rs +++ b/tests/test-cli.rs @@ -55,7 +55,7 @@ fn test_version() { assert_eq!(stderr, ""); let (name, ver) = stdout.split_once(' ').unwrap(); - assert_eq!(name, "cargo-vet"); + assert_eq!(name, "cargo-vet-vet"); let mut ver_parts = ver.trim().split('.'); ver_parts.next().unwrap().parse::().unwrap(); ver_parts.next().unwrap().parse::().unwrap(); From 0555cc8b02c1fbcca91b3b0bffcb5c972df8811b Mon Sep 17 00:00:00 2001 From: Aria Beingessner Date: Fri, 26 Aug 2022 22:48:07 -0400 Subject: [PATCH 2/3] fixup magic header parsing --- src/main.rs | 27 +-- tests/snapshots/test_cli__markdown-help.snap | 205 +++++++++++-------- 2 files changed, 134 insertions(+), 98 deletions(-) diff --git a/src/main.rs b/src/main.rs index 98de29f2..65e618a7 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1625,22 +1625,17 @@ fn cmd_help_md( // Use a trailing colon to indicate a heading if let Some(heading) = line.strip_suffix(':') { if !line.starts_with(' ') { - // SCREAMING headers are Main headings - if heading.to_ascii_uppercase() == heading { - in_subcommands_listing = heading == "SUBCOMMANDS"; - in_usage = heading == "USAGE"; - in_global_options = heading == "GLOBAL OPTIONS"; - - writeln!(out, "### {heading}"); - - if in_global_options && !is_full_command { - writeln!( - out, - "This subcommand accepts all the [global options](#global-options)" - ); - } - } else { - writeln!(out, "### {heading}"); + in_subcommands_listing = heading == "Subcommands"; + in_usage = heading == "Usage"; + in_global_options = heading == "GLOBAL OPTIONS"; + + writeln!(out, "### {heading}"); + + if in_global_options && !is_full_command { + writeln!( + out, + "This subcommand accepts all the [global options](#global-options)" + ); } continue; } diff --git a/tests/snapshots/test_cli__markdown-help.snap b/tests/snapshots/test_cli__markdown-help.snap index 21be1acc..c76e801c 100644 --- a/tests/snapshots/test_cli__markdown-help.snap +++ b/tests/snapshots/test_cli__markdown-help.snap @@ -15,40 +15,29 @@ When run without a subcommand, `cargo vet` will invoke the `check` subcommand. S check` for more details. ### Usage +``` cargo vet [OPTIONS] +``` +``` cargo vet +``` ### Subcommands -check -\[default\] Check that the current project has been vetted -suggest -Suggest some low-hanging fruit to review -init -Initialize cargo-vet for your project -inspect -Fetch the source of a package -diff -Yield a diff against the last reviewed version -certify -Mark a package as audited -regenerate -Explicitly regenerate various pieces of information -add-exemption -Mark a package as exempted from review -record-violation -Declare that some versions of a package violate certain audit criteria -fmt -Reformat all of vet's files (in case you hand-edited them) -fetch-imports -Explicitly fetch the imports (foreign audit files) -dump-graph -Print the cargo build graph as understood by `cargo vet` -gc -Clean up old packages from the vet cache -help -Print this message or the help of the given subcommand(s) - -### Options +* [check](#cargo-vet-check): \[default\] Check that the current project has been vetted +* [suggest](#cargo-vet-suggest): Suggest some low-hanging fruit to review +* [init](#cargo-vet-init): Initialize cargo-vet for your project +* [inspect](#cargo-vet-inspect): Fetch the source of a package +* [diff](#cargo-vet-diff): Yield a diff against the last reviewed version +* [certify](#cargo-vet-certify): Mark a package as audited +* [regenerate](#cargo-vet-regenerate): Explicitly regenerate various pieces of information +* [add-exemption](#cargo-vet-add-exemption): Mark a package as exempted from review +* [record-violation](#cargo-vet-record-violation): Declare that some versions of a package violate certain audit criteria +* [fmt](#cargo-vet-fmt): Reformat all of vet's files (in case you hand-edited them) +* [fetch-imports](#cargo-vet-fetch-imports): Explicitly fetch the imports (foreign audit files) +* [dump-graph](#cargo-vet-dump-graph): Print the cargo build graph as understood by `cargo vet` +* [gc](#cargo-vet-gc): Clean up old packages from the vet cache +* [help](#cargo-vet-help): Print this message or the help of the given subcommand(s) +* [](#cargo-vet-): ### Options #### `--shallow` Avoid suggesting audits for dependencies of unaudited dependencies. @@ -194,7 +183,9 @@ this and prefer adding audits, but if you've done all the audits you plan on doi to finish the job. ### Usage +``` cargo vet check [OPTIONS] +``` ### Options #### `--shallow` @@ -225,7 +216,9 @@ See also `regenerate exemptions`, which can be used to "garbage collect" your ba while `check` is passing). ### Usage +``` cargo vet suggest [OPTIONS] +``` ### Options #### `--shallow` @@ -252,7 +245,9 @@ At this point you can either configure your project further or start working on with `suggest`. ### Usage +``` cargo vet init [OPTIONS] +``` ### Options #### `-h, --help` @@ -269,7 +264,9 @@ We will attempt to guess what criteria you want to audit the package for based o check/suggest status, and show you the meaning of those criteria ahead of time. ### Usage +``` cargo vet inspect [OPTIONS] +``` ### Arguments #### `` @@ -299,7 +296,9 @@ We will attempt to guess what criteria you want to audit the package for based o check/suggest status, and show you the meaning of those criteria ahead of time. ### Usage +``` cargo vet diff [OPTIONS] +``` ### Arguments #### `` @@ -342,7 +341,9 @@ on your backlog and instead use the recommendations of `suggest`. If this removes the need for an `exemption` will we automatically remove it. ### Usage +``` cargo vet certify [OPTIONS] [ARGS] +``` ### Arguments #### `` @@ -401,19 +402,16 @@ automatic if we agree they're boring/reliable enough. See the subcommands for specifics. ### Usage +``` cargo vet regenerate [OPTIONS] +``` ### Subcommands -exemptions -Regenerate your exemptions to make `check` pass minimally -imports -Regenerate your imports and accept changes to criteria -audit-as-crates-io -Regenerate you audit-as-crates-io entries to make `check` pass -help -Print this message or the help of the given subcommand(s) - -### Options +* [exemptions](#cargo-vet-exemptions): Regenerate your exemptions to make `check` pass minimally +* [imports](#cargo-vet-imports): Regenerate your imports and accept changes to criteria +* [audit-as-crates-io](#cargo-vet-audit-as-crates-io): Regenerate you audit-as-crates-io entries to make `check` pass +* [help](#cargo-vet-help): Print this message or the help of the given subcommand(s) +* [](#cargo-vet-): ### Options #### `-h, --help` Print help information @@ -433,7 +431,9 @@ adding only those that are needed. Exemptions that are overbroad may also be wea safe-to-deploy may be reduced to safe-to-run). ### Usage +``` cargo vet regenerate exemptions [OPTIONS] +``` ### Options #### `-h, --help` @@ -450,7 +450,9 @@ This is equivalent to `cargo vet fetch-imports` but it won't produce an error if foreign criteria change. ### Usage +``` cargo vet regenerate imports [OPTIONS] +``` ### Options #### `-h, --help` @@ -466,7 +468,9 @@ Regenerate you audit-as-crates-io entries to make `check` pass This will just set any problematic entries to `audit-as-crates-io = false`. ### Usage +``` cargo vet regenerate audit-as-crates-io [OPTIONS] +``` ### Options #### `-h, --help` @@ -480,45 +484,51 @@ This subcommand accepts all the [global options](#global-options) Print this message or the help of the given subcommand(s) ### Usage +``` cargo vet regenerate help [SUBCOMMAND] +``` ### Subcommands -exemptions -Regenerate your exemptions to make `check` pass minimally -imports -Regenerate your imports and accept changes to criteria -audit-as-crates-io -Regenerate you audit-as-crates-io entries to make `check` pass -help -Print this message or the help of the given subcommand(s) +* [exemptions](#cargo-vet-exemptions): Regenerate your exemptions to make `check` pass minimally +* [imports](#cargo-vet-imports): Regenerate your imports and accept changes to criteria +* [audit-as-crates-io](#cargo-vet-audit-as-crates-io): Regenerate you audit-as-crates-io entries to make `check` pass +* [help](#cargo-vet-help): Print this message or the help of the given subcommand(s)


## cargo vet exemptions Regenerate your exemptions to make `check` pass minimally ### Usage +``` cargo vet regenerate help exemptions +```


## cargo vet imports Regenerate your imports and accept changes to criteria ### Usage +``` cargo vet regenerate help imports +```


## cargo vet audit-as-crates-io Regenerate you audit-as-crates-io entries to make `check` pass ### Usage +``` cargo vet regenerate help audit-as-crates-io +```


## cargo vet help Print this message or the help of the given subcommand(s) ### Usage +``` cargo vet regenerate help help +```


## cargo vet add-exemption @@ -533,7 +543,9 @@ unnecessary ones), so we recommend using that over `add-exemption`. This command "plumbing" for building tools on top of `cargo vet`. ### Usage +``` cargo vet add-exemption [OPTIONS] +``` ### Arguments #### `` @@ -599,7 +611,9 @@ to do about it. There isn't yet a mechanism for dealing with disagreements with violations. ### Usage +``` cargo vet record-violation [OPTIONS] +``` ### Arguments #### `` @@ -644,7 +658,9 @@ Most commands will implicitly do this, so this mostly exists as "plumbing" for b of vet, or in case you don't want to run another command. ### Usage +``` cargo vet fmt [OPTIONS] +``` ### Options #### `-h, --help` @@ -661,7 +677,9 @@ Explicitly fetch the imports (foreign audit files) top of vet. ### Usage +``` cargo vet fetch-imports [OPTIONS] +``` ### Options #### `-h, --help` @@ -689,7 +707,9 @@ the problem will disappear. This can be used to bisect a problem if you get ambi your filters. ### Usage +``` cargo vet dump-graph [OPTIONS] +``` ### Options #### `--depth ` @@ -714,7 +734,9 @@ recognized by cargo-vet. In the future, many cargo-vet subcommands will implicitly do this. ### Usage +``` cargo vet gc [OPTIONS] +``` ### Options #### `--max-package-age-days ` @@ -737,164 +759,183 @@ This subcommand accepts all the [global options](#global-options) Print this message or the help of the given subcommand(s) ### Usage +``` cargo vet help [SUBCOMMAND] +``` ### Subcommands -check -\[default\] Check that the current project has been vetted -suggest -Suggest some low-hanging fruit to review -init -Initialize cargo-vet for your project -inspect -Fetch the source of a package -diff -Yield a diff against the last reviewed version -certify -Mark a package as audited -regenerate -Explicitly regenerate various pieces of information -add-exemption -Mark a package as exempted from review -record-violation -Declare that some versions of a package violate certain audit criteria -fmt -Reformat all of vet's files (in case you hand-edited them) -fetch-imports -Explicitly fetch the imports (foreign audit files) -dump-graph -Print the cargo build graph as understood by `cargo vet` -gc -Clean up old packages from the vet cache -help -Print this message or the help of the given subcommand(s) +* [check](#cargo-vet-check): \[default\] Check that the current project has been vetted +* [suggest](#cargo-vet-suggest): Suggest some low-hanging fruit to review +* [init](#cargo-vet-init): Initialize cargo-vet for your project +* [inspect](#cargo-vet-inspect): Fetch the source of a package +* [diff](#cargo-vet-diff): Yield a diff against the last reviewed version +* [certify](#cargo-vet-certify): Mark a package as audited +* [regenerate](#cargo-vet-regenerate): Explicitly regenerate various pieces of information +* [add-exemption](#cargo-vet-add-exemption): Mark a package as exempted from review +* [record-violation](#cargo-vet-record-violation): Declare that some versions of a package violate certain audit criteria +* [fmt](#cargo-vet-fmt): Reformat all of vet's files (in case you hand-edited them) +* [fetch-imports](#cargo-vet-fetch-imports): Explicitly fetch the imports (foreign audit files) +* [dump-graph](#cargo-vet-dump-graph): Print the cargo build graph as understood by `cargo vet` +* [gc](#cargo-vet-gc): Clean up old packages from the vet cache +* [help](#cargo-vet-help): Print this message or the help of the given subcommand(s)


## cargo vet check \[default\] Check that the current project has been vetted ### Usage +``` cargo vet help check +```


## cargo vet suggest Suggest some low-hanging fruit to review ### Usage +``` cargo vet help suggest +```


## cargo vet init Initialize cargo-vet for your project ### Usage +``` cargo vet help init +```


## cargo vet inspect Fetch the source of a package ### Usage +``` cargo vet help inspect +```


## cargo vet diff Yield a diff against the last reviewed version ### Usage +``` cargo vet help diff +```


## cargo vet certify Mark a package as audited ### Usage +``` cargo vet help certify +```


## cargo vet regenerate Explicitly regenerate various pieces of information ### Usage +``` cargo vet help regenerate [SUBCOMMAND] +``` ### Subcommands -exemptions -Regenerate your exemptions to make `check` pass minimally -imports -Regenerate your imports and accept changes to criteria -audit-as-crates-io -Regenerate you audit-as-crates-io entries to make `check` pass +* [exemptions](#cargo-vet-exemptions): Regenerate your exemptions to make `check` pass minimally +* [imports](#cargo-vet-imports): Regenerate your imports and accept changes to criteria +* [audit-as-crates-io](#cargo-vet-audit-as-crates-io): Regenerate you audit-as-crates-io entries to make `check` pass


## cargo vet exemptions Regenerate your exemptions to make `check` pass minimally ### Usage +``` cargo vet help regenerate exemptions +```


## cargo vet imports Regenerate your imports and accept changes to criteria ### Usage +``` cargo vet help regenerate imports +```


## cargo vet audit-as-crates-io Regenerate you audit-as-crates-io entries to make `check` pass ### Usage +``` cargo vet help regenerate audit-as-crates-io +```


## cargo vet add-exemption Mark a package as exempted from review ### Usage +``` cargo vet help add-exemption +```


## cargo vet record-violation Declare that some versions of a package violate certain audit criteria ### Usage +``` cargo vet help record-violation +```


## cargo vet fmt Reformat all of vet's files (in case you hand-edited them) ### Usage +``` cargo vet help fmt +```


## cargo vet fetch-imports Explicitly fetch the imports (foreign audit files) ### Usage +``` cargo vet help fetch-imports +```


## cargo vet dump-graph Print the cargo build graph as understood by `cargo vet` ### Usage +``` cargo vet help dump-graph +```


## cargo vet gc Clean up old packages from the vet cache ### Usage +``` cargo vet help gc +```


## cargo vet help Print this message or the help of the given subcommand(s) ### Usage +``` cargo vet help help +``` stderr: From 35310deed33d67971063ac92e832df2d4434a47a Mon Sep 17 00:00:00 2001 From: Aria Beingessner Date: Fri, 26 Aug 2022 22:53:51 -0400 Subject: [PATCH 3/3] more magic markdown fixes --- src/main.rs | 12 +++++++----- tests/snapshots/test_cli__markdown-help.snap | 6 ++++-- 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/src/main.rs b/src/main.rs index 65e618a7..109c436c 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1649,11 +1649,13 @@ fn cmd_help_md( if in_subcommands_listing && !line.starts_with(" ") { // subcommand names are list items let own_subcommand_name = line.trim(); - write!( - out, - "* [{own_subcommand_name}](#{app_name}-{own_subcommand_name}): " - ); - continue; + if !own_subcommand_name.is_empty() { + write!( + out, + "* [{own_subcommand_name}](#{app_name}-{own_subcommand_name}): " + ); + continue; + } } // The rest is indented, get rid of that let line = line.trim(); diff --git a/tests/snapshots/test_cli__markdown-help.snap b/tests/snapshots/test_cli__markdown-help.snap index c76e801c..551aba02 100644 --- a/tests/snapshots/test_cli__markdown-help.snap +++ b/tests/snapshots/test_cli__markdown-help.snap @@ -37,7 +37,8 @@ cargo vet * [dump-graph](#cargo-vet-dump-graph): Print the cargo build graph as understood by `cargo vet` * [gc](#cargo-vet-gc): Clean up old packages from the vet cache * [help](#cargo-vet-help): Print this message or the help of the given subcommand(s) -* [](#cargo-vet-): ### Options + +### Options #### `--shallow` Avoid suggesting audits for dependencies of unaudited dependencies. @@ -411,7 +412,8 @@ cargo vet regenerate [OPTIONS] * [imports](#cargo-vet-imports): Regenerate your imports and accept changes to criteria * [audit-as-crates-io](#cargo-vet-audit-as-crates-io): Regenerate you audit-as-crates-io entries to make `check` pass * [help](#cargo-vet-help): Print this message or the help of the given subcommand(s) -* [](#cargo-vet-): ### Options + +### Options #### `-h, --help` Print help information