Do not consider #[doc(hidden)] items part of the public API. (#576)

* Do not consider `#[doc(hidden)]` items part of the public API. * Set `continue-on-error: true` and use nightly temporarily so that CI runs everything. * Check whether associated items are public API as well. * Fix deprecations query. * Add tests for `#[doc(hidden)]` on structs, enums, variants, fields. * Add test cases for module contents and associated items being hidden. * Add test coverage for traits and trait associated items. * Update to latest adapter versions and drop rustdoc v24. * Require minimum Rust 1.71 to work.
obi1kenobi · Nov 8, 2023 · abc6a57 · abc6a57
1 parent add43f4
commit abc6a57
Show file tree

Hide file tree

Showing 92 changed files with 1,009 additions and 73 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -150,7 +150,7 @@ jobs:
         # IMPORTANT: When updating the versions here, make sure you also update
         #            the `fails-on-too-old-rustc` job and its error message to
         #            to account for the raised minimum required version.
-        toolchain: ["1.70", "1.71", "1.72", "stable", "beta"]
+        toolchain: ["1.71", "1.72", "stable", "beta"]
         experimental: [false]
         include:
           - toolchain: "nightly"
@@ -330,7 +330,7 @@ jobs:
         id: toolchain
         uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
-          toolchain: "1.70"  # Rust 1.70 uses rustdoc v24
+          toolchain: "1.73"  # Rust 1.73 uses rustdoc v26
           rustflags: ""
           cache: false
 
@@ -364,11 +364,15 @@ jobs:
       - name: Install newer rust
         uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
-          toolchain: "1.72"  # Rust 1.72 uses rustdoc v26
+          # Make sure this version matches the env var below.
+          toolchain: "nightly"  # Rust 1.75-nightly uses rustdoc v27
+
           rustflags: ""
           cache: false
 
       - name: Check with older rustdoc version cached
+        env:
+          NEWER_RUST_VERSION: "nightly"  # Make sure this matches the version installed just above.
         run: |
           # Use a separate workspace, to avoid contaminating the cache for Swatinem/rust-cache@v2
           cp -R subject subject-new
@@ -385,9 +389,9 @@ jobs:
           export OLD_RUSTDOC_VERSION="$(jq .format_version subject-new/target/semver-checks/cache/registry-libp2p_core-0_37_0.json)"
 
           # Run cargo-semver-checks with the older cached file.
-          # In a prior step, we installed stable Rust, so we'll set that as the default
+          # In a prior step, we installed a newer Rust, so we'll set that as the default
           # for cargo-semver-checks to invoke here.
-          rustup override set stable
+          rustup override set "$NEWER_RUST_VERSION"
           bins/cargo-semver-checks semver-checks check-release --manifest-path="subject-new/core/Cargo.toml" --verbose
 
           export NEW_RUSTDOC_VERSION="$(jq .format_version subject-new/target/semver-checks/cache/registry-libp2p_core-0_37_0.json)"
@@ -1606,7 +1610,7 @@ jobs:
         id: toolchain
         uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
-          toolchain: "1.67"
+          toolchain: "1.70"
           rustflags: ""
           cache: false
 
@@ -1649,7 +1653,7 @@ jobs:
       - name: Check output
         run: |
           cd semver
-          EXPECTED="$(echo -e "Error: rustc version is not high enough: >=1.68.0 needed, got 1.67.1")"
+          EXPECTED="$(echo -e "Error: rustc version is not high enough: >=1.71.0 needed, got 1.70.0")"
           RESULT="$(cat output | grep Error)"
           diff <(echo "$RESULT") <(echo "$EXPECTED")
 

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -15,7 +15,7 @@ rust-version = "1.70"
 
 [dependencies]
 trustfall = "0.6.0"
-trustfall_rustdoc = { version = "0.13.1", default-features = false, features = ["v24", "v26", "v27"] }
+trustfall_rustdoc = { version = "0.13.1", default-features = false, features = ["v26", "v27"] }
 clap = { version = "4.0.0", features = ["derive", "cargo"] }
 serde_json = "1.0.82"
 anyhow = "1.0.58"

diff --git a/src/config.rs b/src/config.rs
@@ -52,7 +52,7 @@ impl GlobalConfig {
                 }
             })),
             handlebars: make_handlebars_registry(),
-            minimum_rustc_version: semver::Version::new(1, 68, 0),
+            minimum_rustc_version: semver::Version::new(1, 71, 0),
         }
     }
 

diff --git a/src/lints/auto_trait_impl_removed.ron b/src/lints/auto_trait_impl_removed.ron
@@ -15,6 +15,7 @@ SemverQuery(
 
                         importable_path {
                             path @output @tag
+                            public_api @filter(op: "=", value: ["$true"])
                         }
 
                         impl {
@@ -44,6 +45,7 @@ SemverQuery(
 
                         importable_path {
                             path @filter(op: "=", value: ["%path"])
+                            public_api @filter(op: "=", value: ["$true"])
                         }
 
                         impl @fold @transform(op: "count") @filter(op: "=", value: ["$zero"]) {
@@ -71,6 +73,7 @@ SemverQuery(
         "public": "public",
         "zero": 0,
         "false": false,
+        "true": true,
         "auto_traits": [
             ["core", "marker", "Send"],
             ["core", "marker", "Sync"],

diff --git a/src/lints/constructible_struct_adds_field.ron b/src/lints/constructible_struct_adds_field.ron
@@ -23,6 +23,7 @@ SemverQuery(
 
                         importable_path {
                             path @output @tag
+                            public_api @filter(op: "=", value: ["$true"])
                         }
 
                         field {
@@ -52,6 +53,7 @@ SemverQuery(
 
                         importable_path {
                             path @filter(op: "=", value: ["%path"])
+                            public_api @filter(op: "=", value: ["$true"])
                         }
 
                         # 2. It needs to not have had any non-public fields.
@@ -72,6 +74,7 @@ SemverQuery(
     arguments: {
         "public": "public",
         "non_exhaustive": "#[non_exhaustive]",
+        "true": true,
         "zero": 0,
     },
     error_message: "A pub struct constructible with a struct literal has a new pub field. Existing struct literals must be updated to include the new field.",

diff --git a/src/lints/constructible_struct_adds_private_field.ron b/src/lints/constructible_struct_adds_private_field.ron
@@ -23,6 +23,7 @@ SemverQuery(
 
                         importable_path {
                             path @output @tag
+                            public_api @filter(op: "=", value: ["$true"])
                         }
 
                         field {
@@ -52,6 +53,7 @@ SemverQuery(
 
                         importable_path {
                             path @filter(op: "=", value: ["%path"])
+                            public_api @filter(op: "=", value: ["$true"])
                         }
 
                         # 2. It needs to not have had any non-public fields.
@@ -72,6 +74,7 @@ SemverQuery(
     arguments: {
         "public": "public",
         "non_exhaustive": "#[non_exhaustive]",
+        "true": true,
         "zero": 0,
     },
     error_message: "A struct constructible with a struct literal has a new non-public field. It can no longer be constructed using a struct literal outside of its crate.",

diff --git a/src/lints/constructible_struct_changed_type.ron b/src/lints/constructible_struct_changed_type.ron
@@ -36,6 +36,7 @@ More info: https://github.com/obi1kenobi/cargo-semver-checks/issues/297
 
                         importable_path {
                             path @output @tag
+                            public_api @filter(op: "=", value: ["$true"])
                         }
                     }
                 }
@@ -50,6 +51,7 @@ More info: https://github.com/obi1kenobi/cargo-semver-checks/issues/297
 
                         importable_path {
                             path @filter(op: "=", value: ["%path"])
+                            public_api @filter(op: "=", value: ["$true"])
                         }
 
                         span_: span @optional {
@@ -64,6 +66,7 @@ More info: https://github.com/obi1kenobi/cargo-semver-checks/issues/297
     arguments: {
         "public": "public",
         "non_exhaustive": "#[non_exhaustive]",
+        "true": true,
         "zero": 0,
     },
     error_message: "A struct became an enum or union, and is no longer publicly constructible with a struct literal.",

diff --git a/src/lints/derive_trait_impl_removed.ron b/src/lints/derive_trait_impl_removed.ron
@@ -16,6 +16,7 @@ SemverQuery(
 
                         importable_path {
                             path @output @tag
+                            public_api @filter(op: "=", value: ["$true"])
                         }
 
                         impl {
@@ -52,6 +53,7 @@ SemverQuery(
 
                         importable_path @fold @transform(op: "count") @filter(op: ">", value: ["$zero"]) {
                             path @filter(op: "=", value: ["%path"])
+                            public_api @filter(op: "=", value: ["$true"])
                         }
 
                         impl @fold @transform(op: "count") @filter(op: "=", value: ["$zero"]) {
@@ -87,6 +89,7 @@ SemverQuery(
         "public": "public",
         "zero": 0,
         "false": false,
+        "true": true,
         "structural_eq": ["core", "marker", "StructuralEq"],
     },
     error_message: "A public type has stopped deriving one or more traits. This can break downstream code that depends on those types implementing those traits.",

diff --git a/src/lints/enum_marked_non_exhaustive.ron b/src/lints/enum_marked_non_exhaustive.ron
@@ -18,6 +18,7 @@ SemverQuery(
 
                         importable_path {
                             path @output @tag
+                            public_api @filter(op: "=", value: ["$true"])
                         }
 
                         span_: span @optional {
@@ -35,6 +36,7 @@ SemverQuery(
 
                         importable_path {
                             path @filter(op: "=", value: ["%path"])
+                            public_api @filter(op: "=", value: ["$true"])
                         }
                     }
                 }
@@ -44,6 +46,7 @@ SemverQuery(
     arguments: {
         "public": "public",
         "non_exhaustive": "#[non_exhaustive]",
+        "true": true,
     },
     error_message: "A public enum has been marked #[non_exhaustive]. Pattern-matching on it outside of its crate must now include a wildcard pattern like `_`, or it will fail to compile.",
     per_result_error_template: Some("enum {{name}} in {{span_filename}}:{{span_begin_line}}"),

diff --git a/src/lints/enum_missing.ron b/src/lints/enum_missing.ron
@@ -15,6 +15,7 @@ SemverQuery(
 
                         importable_path {
                             path @output @tag
+                            public_api @filter(op: "=", value: ["$true"])
                         }
 
                         span_: span @optional {
@@ -40,6 +41,7 @@ SemverQuery(
     arguments: {
         "public": "public",
         "zero": 0,
+        "true": true,
     },
     error_message: "A publicly-visible enum cannot be imported by its prior path. A `pub use` may have been removed, or the enum itself may have been renamed or removed entirely.",
     per_result_error_template: Some("enum {{join \"::\" path}}, previously in file {{span_filename}}:{{span_begin_line}}"),
-Original file line number
+Diff line change
@@ Expand Up / @@ -52,7 +52,7 @@ impl GlobalConfig { @@
                     }
                 })),
                 handlebars: make_handlebars_registry(),
-                minimum_rustc_version: semver::Version::new(1, 68, 0),
+                minimum_rustc_version: semver::Version::new(1, 71, 0),
             }
         }
@@ Expand Down @@