NOISSUE - Create lib.rs, to allow documentation tests to be written…

… and run: * Add high level description of public modules in `lib.rs` * Add docs and doc-tests for args module * Add clippy level to enforce use of doc markdown * Add disclaimer that lib is not stable * Update README to include disclaimer * Pull changelog to its own file Signed-off-by: joshmc <[email protected]>
geiger-rs · Dec 4, 2020 · 49c098a · 49c098a
1 parent a7e902d
commit 49c098a
Show file tree

Hide file tree

Showing 12 changed files with 224 additions and 171 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,140 @@
+# Changelog
+---------
+
+## 0.11.0
+ - TODO: Prepare release.
+
+## 0.10.2
+ - __Bugfix__: Avoid panic and log warnings on parse failure. [#105]
+ - Upgraded all dependencies.
+
+## 0.10.1
+ - Expose the `cargo` crate feature: `vendored-openssl`. [#99]
+ - Upgraded all dependencies.
+
+## 0.10.0
+ - Upgraded all dependencies. [#98]
+
+## 0.9.1
+ - __Bugfix__: Avoid counting the same crate multiple times. [#79]
+ - Upgraded cargo to 0.41. [#85]
+ - Upgraded all dependencies.
+
+## 0.9.0
+ - __Breaking change__: Replaced structopt & clap with [pico-args], to reduce 
+   compile times [#77]. As a result the `-Z` flag now requires quotes around
+   its list of sub arguments, other than that there should be no changes to 
+   the CLI.
+
+## 0.8.0
+ - __Bugfix:__ Count all expressions in unsafe functions and nested unsafe
+   scopes, in [geiger 0.4.1](geiger), [#72] & [#71].
+ - __Bugfix:__ Properly account for possibly patched dependencies [#70].
+ - Summary for each metrics column, [#76].
+ - Now requires all entry points for a crate to declare
+   `#[forbid(unsafe_code)]` for it to count as crate-wide.
+ - New optional scan mode `--forbid-only`. This mode doesn't require any calls
+   to `rustc` and only requires parsing the entry point `.rs` files, making it
+   much faster than the normal mode.
+ - Updated dependencies.
+
+## 0.7.3
+ - __Bugfix:__ Fix dependency collection for mixed workspaces [#66].
+ - Updated dependencies.
+
+## 0.7.2
+ - Updated dependencies to fix [#59].
+
+## 0.7.1
+ - __Bugfix:__ related to attributes, in [geiger] [#57].
+ - Updated all dependencies.
+
+## 0.7.0
+ - Updated all dependencies, [geiger] to 0.3.0.
+
+## 0.6.1
+ - A tiny readme fix.
+
+## 0.6.0
+ - There are now three crate scanning result variants [#52]:
+   - 🔒 No unsafe usage found and all build target entry point `.rs` source
+     files, used by the build, declare `#![forbid(unsafe_code)]`. Crates like
+     this will be printed in green.
+   - ❓ No unsafe usage found, but at least one build target entry point `.rs`
+     file, used by the build, does not declare `#[forbid(unsafe_code)]`.  Crates
+     like this will be printed in the default terminal foreground color.
+   - ☢️  Unsafe usage found. Crates like this will be printed in red, same as in
+     the previous version.
+
+## 0.5.0
+ - Moved reusable parts, decoupled from `cargo`, to the new crate
+   [geiger]. Main github issue: [#30].
+ - Some general refactoring and cleanup.
+ - Merge pull request [#46] from alexmaco/dependency_kind_control. add options
+   to filter dependencies by kind; defaults to Kind::Normal.
+ - Merge pull request [#40] from jiminhsieh/rust-2018. Use Rust 2018 edition.
+
+## 0.4.2
+ - __Bugfix:__ Merge pull request [#33] from ajpaverd/windows_filepaths.
+   Canonicalize file paths from walker.
+
+ - Merge pull request [#38] from anderejd/updated-deps. Updated deps and fixed
+   build errors.
+
+## 0.4.1
+ - Merge pull request [#28] from alexmaco/deps_upgrade. fix build on rust 1.30:
+   upgrade petgraph to 0.4.13
+
+ - __Bugfix:__ Merge pull request [#29] from alexmaco/invalid_utf8_source. fix 
+   handling source files with invalid utf8: lossy conversion to string
+
+## 0.4.0
+ - Filters out tests by default. Tests can still be included by using
+   `--include-tests`. The test code is filtered out by looking for the attribute
+   `#[test]` on functions and `#[cfg(test)]` on modules.
+
+## 0.3.1
+ - __Bugfix:__ Some bugfixes related to cargo workspace path handling.
+ - Slightly better error messages in some cases.
+
+## 0.3.0
+ - Intercepts `rustc` calls and reads the `.d` files generated by `rustc` to
+   identify which `.rs` files are used by the build. This allows a crate that
+   contains `.rs` files with unsafe code usage to pass as "green" if the unsafe
+   code isn't used by the build.
+ - Each metric is now printed as `x/y`, where `x` is the unsafe code used by the
+   build and `y` is the total unsafe usage found in the crate.
+ - Removed the `--compact` output format to avoid some code complexity. A new
+   and better compact mode can be added later if requested.
+
+## 0.2.0
+ - Table based output format [#9].
+
+## 0.1.x
+ - Initial experimental versions.
+ - Mostly README.md updates.
+
+[#9]: https://github.com/rust-secure-code/cargo-geiger/pull/9
+[#28]: https://github.com/rust-secure-code/cargo-geiger/issues/28
+[#29]: https://github.com/rust-secure-code/cargo-geiger/issues/29
+[#30]: https://github.com/rust-secure-code/cargo-geiger/issues/30
+[#33]: https://github.com/rust-secure-code/cargo-geiger/issues/33
+[#38]: https://github.com/rust-secure-code/cargo-geiger/issues/38
+[#40]: https://github.com/rust-secure-code/cargo-geiger/issues/40
+[#46]: https://github.com/rust-secure-code/cargo-geiger/issues/46
+[#52]: https://github.com/rust-secure-code/cargo-geiger/issues/52
+[#57]: https://github.com/rust-secure-code/cargo-geiger/issues/57
+[#59]: https://github.com/rust-secure-code/cargo-geiger/issues/59
+[#66]: https://github.com/rust-secure-code/cargo-geiger/issues/66
+[#70]: https://github.com/rust-secure-code/cargo-geiger/pull/70
+[#71]: https://github.com/rust-secure-code/cargo-geiger/issues/71
+[#72]: https://github.com/rust-secure-code/cargo-geiger/pull/72
+[#76]: https://github.com/rust-secure-code/cargo-geiger/pull/76
+[#77]: https://github.com/rust-secure-code/cargo-geiger/pull/77
+[#79]: https://github.com/rust-secure-code/cargo-geiger/issues/79
+[#85]: https://github.com/rust-secure-code/cargo-geiger/pull/85
+[#98]: https://github.com/rust-secure-code/cargo-geiger/pull/98
+[#99]: https://github.com/rust-secure-code/cargo-geiger/pull/99
+[#105]: https://github.com/rust-secure-code/cargo-geiger/issues/105
+[geiger]: https://crates.io/crates/geiger
+[pico-args]: https://crates.io/crates/pico-args
diff --git a/README.md b/README.md
@@ -76,150 +76,20 @@ Roadmap
  - ~~There should be no false negatives. All unsafe code should be
    identified.~~ This is probably too ambitious, but scanning for
    `#![forbid(unsafe_code)]` should be a reliable alternative (implemented since
-   0.6.0). Please see the changelog.
+   0.6.0). Please see the [changelog].
  - An optional whitelist file at the root crate level to specify crates that are
    trusted to use unsafe (should only have an effect if placed in the root
    project).
 
-
-Changelog
+Libraries
 ---------
 
-### 0.11.0
- - TODO: Prepare release.
-
-### 0.10.2
- - __Bugfix__: Avoid panic and log warnings on parse failure. [#105]
- - Upgraded all dependencies.
-
-### 0.10.1
- - Expose the `cargo` crate feature: `vendored-openssl`. [#99]
- - Upgraded all dependencies.
-
-### 0.10.0
- - Upgraded all dependencies. [#98]
-
-### 0.9.1
- - __Bugfix__: Avoid counting the same crate multiple times. [#79]
- - Upgraded cargo to 0.41. [#85]
- - Upgraded all dependencies.
-
-### 0.9.0
- - __Breaking change__: Replaced structopt & clap with [pico-args], to reduce 
-   compile times [#77]. As a result the `-Z` flag now requires quotes around
-   its list of sub arguments, other than that there should be no changes to 
-   the CLI.
-
-### 0.8.0
- - __Bugfix:__ Count all expressions in unsafe functions and nested unsafe
-   scopes, in [geiger 0.4.1](geiger), [#72] & [#71].
- - __Bugfix:__ Properly account for possibly patched dependencies [#70].
- - Summary for each metrics column, [#76].
- - Now requires all entry points for a crate to declare
-   `#[forbid(unsafe_code)]` for it to count as crate-wide.
- - New optional scan mode `--forbid-only`. This mode doesn't require any calls
-   to `rustc` and only requires parsing the entry point `.rs` files, making it
-   much faster than the normal mode.
- - Updated dependencies.
-
-### 0.7.3
- - __Bugfix:__ Fix dependency collection for mixed workspaces [#66].
- - Updated dependencies.
-
-### 0.7.2
- - Updated dependencies to fix [#59].
-
-### 0.7.1
- - __Bugfix:__ related to attributes, in [geiger] [#57].
- - Updated all dependencies.
-
-### 0.7.0
- - Updated all dependencies, [geiger] to 0.3.0.
-
-### 0.6.1
- - A tiny readme fix.
-
-### 0.6.0
- - There are now three crate scanning result variants [#52]:
-   - 🔒 No unsafe usage found and all build target entry point `.rs` source
-     files, used by the build, declare `#![forbid(unsafe_code)]`. Crates like
-     this will be printed in green.
-   - ❓ No unsafe usage found, but at least one build target entry point `.rs`
-     file, used by the build, does not declare `#[forbid(unsafe_code)]`.  Crates
-     like this will be printed in the default terminal foreground color.
-   - ☢️  Unsafe usage found. Crates like this will be printed in red, same as in
-     the previous version.
-
-### 0.5.0
- - Moved reusable parts, decoupled from `cargo`, to the new crate
-   [geiger]. Main github issue: [#30].
- - Some general refactoring and cleanup.
- - Merge pull request [#46] from alexmaco/dependency_kind_control. add options
-   to filter dependencies by kind; defaults to Kind::Normal.
- - Merge pull request [#40] from jiminhsieh/rust-2018. Use Rust 2018 edition.
-
-### 0.4.2
- - __Bugfix:__ Merge pull request [#33] from ajpaverd/windows_filepaths.
-   Canonicalize file paths from walker.
-
- - Merge pull request [#38] from anderejd/updated-deps. Updated deps and fixed
-   build errors.
-
-### 0.4.1
- - Merge pull request [#28] from alexmaco/deps_upgrade. fix build on rust 1.30:
-   upgrade petgraph to 0.4.13
-
- - __Bugfix:__ Merge pull request [#29] from alexmaco/invalid_utf8_source. fix 
-   handling source files with invalid utf8: lossy conversion to string
-
-### 0.4.0
- - Filters out tests by default. Tests can still be included by using
-   `--include-tests`. The test code is filtered out by looking for the attribute
-   `#[test]` on functions and `#[cfg(test)]` on modules.
-
-### 0.3.1
- - __Bugfix:__ Some bugfixes related to cargo workspace path handling.
- - Slightly better error messages in some cases.
-
-### 0.3.0
- - Intercepts `rustc` calls and reads the `.d` files generated by `rustc` to
-   identify which `.rs` files are used by the build. This allows a crate that
-   contains `.rs` files with unsafe code usage to pass as "green" if the unsafe
-   code isn't used by the build.
- - Each metric is now printed as `x/y`, where `x` is the unsafe code used by the
-   build and `y` is the total unsafe usage found in the crate.
- - Removed the `--compact` output format to avoid some code complexity. A new
-   and better compact mode can be added later if requested.
-
-### 0.2.0
- - Table based output format [#9].
-
-### 0.1.x
- - Initial experimental versions.
- - Mostly README.md updates.
-
-[#9]: https://github.com/rust-secure-code/cargo-geiger/pull/9
-[#28]: https://github.com/rust-secure-code/cargo-geiger/issues/28
-[#29]: https://github.com/rust-secure-code/cargo-geiger/issues/29
-[#30]: https://github.com/rust-secure-code/cargo-geiger/issues/30
-[#33]: https://github.com/rust-secure-code/cargo-geiger/issues/33
-[#38]: https://github.com/rust-secure-code/cargo-geiger/issues/38
-[#40]: https://github.com/rust-secure-code/cargo-geiger/issues/40
-[#46]: https://github.com/rust-secure-code/cargo-geiger/issues/46
-[#52]: https://github.com/rust-secure-code/cargo-geiger/issues/52
-[#57]: https://github.com/rust-secure-code/cargo-geiger/issues/57
-[#59]: https://github.com/rust-secure-code/cargo-geiger/issues/59
-[#66]: https://github.com/rust-secure-code/cargo-geiger/issues/66
-[#70]: https://github.com/rust-secure-code/cargo-geiger/pull/70
-[#71]: https://github.com/rust-secure-code/cargo-geiger/issues/71
-[#72]: https://github.com/rust-secure-code/cargo-geiger/pull/72
-[#76]: https://github.com/rust-secure-code/cargo-geiger/pull/76
-[#77]: https://github.com/rust-secure-code/cargo-geiger/pull/77
-[#79]: https://github.com/rust-secure-code/cargo-geiger/issues/79
-[#85]: https://github.com/rust-secure-code/cargo-geiger/pull/85
-[#98]: https://github.com/rust-secure-code/cargo-geiger/pull/98
-[#99]: https://github.com/rust-secure-code/cargo-geiger/pull/99
-[#105]: https://github.com/rust-secure-code/cargo-geiger/issues/105
-[geiger]: https://crates.io/crates/geiger
-[pico-args]: https://crates.io/crates/pico-args
+Cargo Geiger exposes three libraries:
+
+ - `cargo-geiger` - Unversioned and highly unstable library exposing the internals of the `cargo-geiger` binary. As such any function contained within this library may be subject to change.
+ - `cargo-geiger-serde` - A library containing the serializable report types
+ - `geiger` - A library containing some components used by [cargo-geiger] that are decoupled from [cargo]
 
+[cargo]: https://crates.io/crates/cargo
+[cargo-geiger]: https://crates.io/crates/cargo-geiger
+[changelog]: https://github.com/rust-secure-code/cargo-geiger/blob/master/CHANGELOG.md
diff --git a/cargo-geiger-serde/Cargo.toml b/cargo-geiger-serde/Cargo.toml
@@ -1,9 +1,12 @@
 [package]
 authors = ["anderejd <[email protected]>"]
+categories = ["development-tools", "serialization"]
 description = "TODO: Write description"
 edition = "2018"
 license = "Apache-2.0/MIT"
+keywords = ["unsafe"]
 name = "cargo-geiger-serde"
+repository = "https://github.com/rust-secure-code/cargo-geiger"
 version = "0.1.0"
 
 [dependencies]

diff --git a/cargo-geiger/src/args.rs b/cargo-geiger/src/args.rs
@@ -6,6 +6,7 @@ use cargo::{CliResult, Config};
 use pico_args::Arguments;
 use std::path::PathBuf;
 
+/// Constant `&str` containing help text
 pub const HELP: &str =
     "Detects usage of unsafe Rust in a Rust crate and its dependencies.
 
@@ -89,6 +90,13 @@ pub struct Args {
 }
 
 impl Args {
+    /// Construct `Args` struct from `pico_args::Arguments` loaded from command line arguments
+    /// provided by the user
+    /// ```
+    /// # use cargo_geiger::args::Args;
+    /// let pico_arguments = pico_args::Arguments::from_env();
+    /// let args = Args::parse_args(pico_arguments);
+    /// ```
     pub fn parse_args(
         mut raw_args: Arguments,
     ) -> Result<Args, Box<dyn std::error::Error>> {
@@ -152,6 +160,17 @@ impl Args {
         Ok(args)
     }
 
+    /// Update `cargo::util::Config` with values from `Args` struct, and set the shell
+    /// colour choice
+    /// ```
+    /// # use cargo::Config;
+    /// # use cargo_geiger::args::Args;
+    /// let args = Args::parse_args(
+    ///     pico_args::Arguments::from_env()
+    /// ).unwrap();
+    /// let mut config = Config::default().unwrap();
+    /// args.update_config(&mut config);
+    /// ```
     pub fn update_config(&self, config: &mut Config) -> CliResult {
         let target_dir = None; // Doesn't add any value for cargo-geiger.
         config.configure(

diff --git a/cargo-geiger/src/cli.rs b/cargo-geiger/src/cli.rs
@@ -1,5 +1,3 @@
-//! This module provides the bulk of the code for the `cargo-geiger` executable.
-
 // TODO: Review the module structure in this crate. There is very tight coupling
 // between the main.rs and this module. Should this module be split into smaller
 // parts? The printing and scanning can probably be further decoupled to provide
@@ -8,7 +6,7 @@
 // TODO: Investigate how cargo-clippy is implemented. Is it using syn?  Is is
 // using rustc? Is it implementing a compiler plugin?
 
-use crate::Args;
+use crate::args::Args;
 
 // TODO: Consider making this a lib.rs (again) and expose a full API, excluding
 // only the terminal output..? That API would be dependent on cargo.
@@ -53,7 +51,7 @@ pub fn get_cargo_metadata(
 
 /// TODO: Write proper documentation for this.
 /// This function seems to be looking up the active flags for conditional
-/// compilation (cargo_platform::Cfg instances).
+/// compilation (`cargo_platform::Cfg` instances).
 pub fn get_cfgs(
     config: &Config,
     target: &Option<String>,