Next iteration

deny.schema.json

@@ -4,6 +4,9 @@
     "advisories": {
       "$ref": "#/definitions/Advisories"
     },
+    "bans": {
+      "$ref": "#/definitions/Bans"
+    },
     "graph": {
       "$ref": "#/definitions/Graph"
     },
@@ -190,7 +193,7 @@
           "description": "Every advisory in the advisory database contains a unique identifier, eg. `RUSTSEC-2019-0001`.\nPutting an identifier in this array will cause the advisory to be treated as a note, rather\nthan a warning or error.\n\nIn addition, yanked crate versions can be ignored by specifying a [PackageSpec](https://embarkstudios.github.io/cargo-deny/checks/cfg.html#package-spec)\nwith an optional `reason`.\n"
         }
       },
-      "description": "Checks advisory databases for crates with security vulnerabilities,\nor that have been marked as Unmaintained, or which have been yanked from\ntheir source registry.\n\nThis section is considered when running `cargo deny check advisories`.\n"
+      "title": "Checks advisory databases for crates with security vulnerabilities,\nor that have been marked as Unmaintained, or which have been yanked from\ntheir source registry.\n\nThis section is considered when running `cargo deny check advisories`.\n"
     },
     "AdvisoriesIgnoreAdvisory": {
       "type": "object",
@@ -241,6 +244,22 @@
         "crate"
       ]
     },
+    "Bans": {
+      "type": "object",
+      "properties": {
+        "allow": {
+          "$ref": "#/definitions/BansAllow"
+        }
+      },
+      "title": "Checks for specific crates in your graph, as well as duplicates.\n\nThis section is considered when running `cargo deny check bans`.\n"
+    },
+    "BansAllow": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/PackageSpec"
+      },
+      "description": "Determines specific crates that are allowed. If the `allow` list has one or more entries, then\nany crate not in that list will be denied, so use with care. Each entry uses the same\n[PackageSpec](https://embarkstudios.github.io/cargo-deny/checks/cfg.html#package-spec)\nas other parts of cargo-deny's configuration.\n"
+    },
     "Graph": {
       "type": "object",
       "properties": {
@@ -284,7 +303,7 @@
           "description": "If set to `true`, all `dev-dependencies`, even one for workspace crates, are not included\nin the crate graph used for any of the checks. This option can also be enabled on cmd line\nwith `--exclude-dev` either [before](https://embarkstudios.github.io/cargo-deny/cli/common.html#--exclude-dev)\nor [after](https://embarkstudios.github.io/cargo-deny/cli/check.html#--exclude-dev)\nthe `check` subcommand.\n"
         }
       },
-      "description": "The graph table configures how the dependency graph is constructed and thus which crates the\nchecks are performed against\n"
+      "title": "The graph table configures how the dependency graph is constructed and thus which crates the\nchecks are performed against\n"
     },
     "IgnoreReason": {
       "type": "string",
@@ -316,7 +335,7 @@
           "default": 1
         }
       },
-      "description": "The output table provides options for how/if diagnostics are outputted"
+      "title": "The output table provides options for how/if diagnostics are outputted"
     },
     "PackageSpec": {
       "type": "string",
@@ -378,6 +397,9 @@
     "advisories": {
       "$ref": "#/definitions/Advisories"
     },
+    "bans": {
+      "$ref": "#/definitions/Bans"
+    },
     "graph": {
       "$ref": "#/definitions/Graph"
     },

deny.schema.yml

@@ -36,6 +36,7 @@ description: Full documentation is at https://embarkstudios.github.io/cargo-deny
 type: object
 properties:
   advisories: { $ref: "#/definitions/Advisories" }
+  bans: { $ref: "#/definitions/Bans" }
   graph: { $ref: "#/definitions/Graph" }
   output: { $ref: "#/definitions/Output" }
 
@@ -55,14 +56,12 @@ definitions:
           - { crate: yanked, reason: a new version has not been released }
         severity-threshold: medium
 
-    description: |
+    title: |
       Checks advisory databases for crates with security vulnerabilities,
       or that have been marked as Unmaintained, or which have been yanked from
       their source registry.
 
       This section is considered when running `cargo deny check advisories`.
-    # More documentation for the advisories section can be found
-    # [here](https://embarkstudios.github.io/cargo-deny/checks/advisories/cfg.html)
 
     type: object
     properties:
@@ -289,8 +288,27 @@ definitions:
       The old format uses a required `name` key and an optional `version` key. This format is deprecated
       and should not be used.
 
-  Graph:
+  Bans:
+    title: |
+      Checks for specific crates in your graph, as well as duplicates.
+
+      This section is considered when running `cargo deny check bans`.
+
+    type: object
+    properties:
+      allow: { $ref: "#/definitions/BansAllow" }
+
+  BansAllow:
+    type: array
+    items: { $ref: "#/definitions/PackageSpec" }
     description: |
+      Determines specific crates that are allowed. If the `allow` list has one or more entries, then
+      any crate not in that list will be denied, so use with care. Each entry uses the same
+      [PackageSpec](https://embarkstudios.github.io/cargo-deny/checks/cfg.html#package-spec)
+      as other parts of cargo-deny's configuration.
+
+  Graph:
+    title: |
       The graph table configures how the dependency graph is constructed and thus which crates the
       checks are performed against
 
@@ -401,7 +419,7 @@ definitions:
       expressions require us to know the details about the target.
 
   Output:
-    description: The output table provides options for how/if diagnostics are outputted
+    title: The output table provides options for how/if diagnostics are outputted
     type: object
     properties:
       feature-depth:

docs/src/checks2/advisories/cfg.md

@@ -249,80 +249,9 @@ ignore = ["RUSTSEC-2019-0001"]
 
 ##### `advisories.ignore[N] (as Yanked).crate`
 
-**Type:** `string`<br>
+**Type:** [`PackageSpec`](/checks2/type-index.html#packagespec) `(string)`<br>
 **Required:** `yes`
 
-Many configuration options require a package specifier at a minimum, which we'll describe here.
-The options that use package specifiers will be called out in their individual documentation.
-We'll use the [`bans.deny`](bans/cfg.md#the-deny-field-optional) option in the following examples.
-
-### String format
-
-If the particular only requires a package spec at a minimum, then the string format can be used,
-which comes in three forms.
-
-#### Simple
-
-```toml
-# Will match any version of the simple crate
-deny = ["simple"]
-```
-
-The simplest string is one which is just the crate name. In this case, the version requirement
-used when checking will be `*` meaning it will match against all versions of that crate in the graph.
-
-#### With Version Requirements
-
-```toml
-# Will match only these versions of the simple crate that match the predicate(s)
-deny = ["simple:<=0.1,>0.2"]
-```
-
-If you want to apply version requirements (predicates) to the crate, simply append them following
-a `:` separator.
-
-#### Exact
-
-```toml
-# Will match only this exact version of the simple crate
-deny = [
-    "[email protected]",
-    # This is semantically equivalent to the above
-    "simple:=0.1.0",
-]
-```
-
-The exact form is a specialization of the version requirements, where the semver after the `@`
-is transformed to be [= (Exact)](https://docs.rs/semver/latest/semver/enum.Op.html#opexact).
-
-### Table format
-
-#### Crate format
-
-```toml
-deny = [
-    { crate = "[email protected]" }, # equivalent to "[email protected]"
-    { crate = "simple", wrappers = ["example"] },
-]
-```
-
-The crate format is a replacement for the old `name` and/or `version` table format. It uses
-the string format described above in a single `crate` key.
-
-#### Old format
-
-```toml
-deny = [
-    { name = "simple" },
-    { name = "simple", version = "*" }
-    { name = "simple", wrappers = ["example"] }
-]
-```
-
-The old format uses a required `name` key and an optional `version` key. This format is deprecated
-and should not be used.
-
-
 ##### `advisories.ignore[N] (as Yanked).reason`
 
 **Type:** [`IgnoreReason`](/checks2/type-index.html#ignorereason) `(string)`<br>

docs/src/checks2/bans/cfg.md

@@ -1 +1,24 @@
-# config
+# `bans`
+
+**Type:** `object`<br>
+**Required:** `no`
+
+Checks for specific crates in your graph, as well as duplicates.
+
+This section is considered when running `cargo deny check bans`.
+
+
+## `bans.allow`
+
+**Type:** `array`<br>
+**Required:** `no`
+
+Determines specific crates that are allowed. If the `allow` list has one or more entries, then
+any crate not in that list will be denied, so use with care. Each entry uses the same
+[PackageSpec](https://embarkstudios.github.io/cargo-deny/checks/cfg.html#package-spec)
+as other parts of cargo-deny's configuration.
+
+
+### Items
+
+**Type:** [`PackageSpec`](/checks2/type-index.html#packagespec) `(string)`

docs/src/checks2/cfg.md

@@ -10,12 +10,34 @@ The top level config for cargo-deny, by default called `deny.toml`.
 
 ## The `[advisories]` section
 
+Checks advisory databases for crates with security vulnerabilities,
+or that have been marked as Unmaintained, or which have been yanked from
+their source registry.
+
+This section is considered when running `cargo deny check advisories`.
+
+
 See [advisories config](advisories/cfg.html) for more info.
 
+## The `[bans]` section
+
+Checks for specific crates in your graph, as well as duplicates.
+
+This section is considered when running `cargo deny check bans`.
+
+
+See [bans config](bans/cfg.html) for more info.
+
 ## The `[graph]` section
 
+The graph table configures how the dependency graph is constructed and thus which crates the
+checks are performed against
+
+
 See [graph config](graph/cfg.html) for more info.
 
 ## The `[output]` section
 
+The output table provides options for how/if diagnostics are outputted
+
 See [output config](output/cfg.html) for more info.

docs/src/checks2/type-index.md

@@ -20,6 +20,81 @@ Free-form string that can be used to describe the reason why the advisory is ign
 
 - `"allow"` - Print a note about the problem, but don't fail the check.
 
+## `PackageSpec`
+
+**Type:** `string`
+
+Many configuration options require a package specifier at a minimum, which we'll describe here.
+The options that use package specifiers will be called out in their individual documentation.
+We'll use the [`bans.deny`](bans/cfg.md#the-deny-field-optional) option in the following examples.
+
+### String format
+
+If the particular only requires a package spec at a minimum, then the string format can be used,
+which comes in three forms.
+
+#### Simple
+
+```toml
+# Will match any version of the simple crate
+deny = ["simple"]
+```
+
+The simplest string is one which is just the crate name. In this case, the version requirement
+used when checking will be `*` meaning it will match against all versions of that crate in the graph.
+
+#### With Version Requirements
+
+```toml
+# Will match only these versions of the simple crate that match the predicate(s)
+deny = ["simple:<=0.1,>0.2"]
+```
+
+If you want to apply version requirements (predicates) to the crate, simply append them following
+a `:` separator.
+
+#### Exact
+
+```toml
+# Will match only this exact version of the simple crate
+deny = [
+    "[email protected]",
+    # This is semantically equivalent to the above
+    "simple:=0.1.0",
+]
+```
+
+The exact form is a specialization of the version requirements, where the semver after the `@`
+is transformed to be [= (Exact)](https://docs.rs/semver/latest/semver/enum.Op.html#opexact).
+
+### Table format
+
+#### Crate format
+
+```toml
+deny = [
+    { crate = "[email protected]" }, # equivalent to "[email protected]"
+    { crate = "simple", wrappers = ["example"] },
+]
+```
+
+The crate format is a replacement for the old `name` and/or `version` table format. It uses
+the string format described above in a single `crate` key.
+
+#### Old format
+
+```toml
+deny = [
+    { name = "simple" },
+    { name = "simple", version = "*" }
+    { name = "simple", wrappers = ["example"] }
+]
+```
+
+The old format uses a required `name` key and an optional `version` key. This format is deprecated
+and should not be used.
+
+
 ## `TargetString`
 
 **Type:** `string`

xtask/src/cli/codegen/md_doc/rendering.rs

@@ -27,6 +27,8 @@ impl Doc {
             let key = &section.data.key;
             let header = format!("The `[{key}]` section");
             let body = format!("See [{key} config]({key}/cfg.html) for more info.");
+            let body = itertools::chain(&section.data.title, [&body]).join("\n\n");
+
             RenderedSection::leaf(header, body)
         });