generate snapshots of the Rust public API (NomicFoundation#1081)

This will make sure any additions/removals impacting users is accounted
for.

Cargo.toml

@@ -122,10 +122,12 @@ num-format = { version = "0.4.4" }
 once_cell = { version = "1.19.0" }
 paste = { version = "1.0.15" }
 proc-macro2 = { version = "1.0.86" }
+public-api = { version = "0.37.0" }
 quote = { version = "1.0.36" }
 rayon = { version = "1.10.0" }
 regex = { version = "1.10.5" }
 reqwest = { version = "0.12.5", features = ["blocking"] }
+rustdoc-json = { version = "0.9.2" }
 semver = { version = "1.0.23", features = ["serde"] }
 serde = { version = "1.0.204", features = ["derive", "rc"] }
 serde_json = { version = "1.0.121", features = ["preserve_order"] }

crates/infra/cli/src/commands/publish/cargo/mod.rs

@@ -3,23 +3,15 @@ use std::path::Path;
 
 use anyhow::Result;
 use clap::Parser;
-use infra_utils::cargo::CargoWorkspace;
+use infra_utils::cargo::{CargoWorkspace, UserFacingCrate};
 use infra_utils::commands::Command;
 use infra_utils::git::TemporaryChangeset;
 use infra_utils::paths::PathExtensions;
 use itertools::Itertools;
+use strum::IntoEnumIterator;
 
 use crate::utils::DryRun;
 
-const USER_FACING_CRATES: &[&str] = &[
-    // Sorted by dependency order (from dependencies to dependents):
-    "metaslang_cst",
-    "metaslang_graph_builder",
-    "metaslang_bindings",
-    "slang_solidity",
-    "slang_solidity_cli",
-];
-
 #[derive(Clone, Debug, Parser)]
 pub struct CargoController {
     #[command(flatten)]
@@ -35,8 +27,10 @@ impl CargoController {
 
         let mut changed_crates = vec![];
 
-        for crate_name in USER_FACING_CRATES {
-            if prepare_for_publish(crate_name, &mut changeset)? {
+        for crate_name in UserFacingCrate::iter() {
+            let crate_name = crate_name.to_string();
+
+            if prepare_for_publish(&crate_name, &mut changeset)? {
                 changed_crates.push(crate_name);
             }
         }

crates/infra/cli/src/commands/setup/cargo/mod.rs

@@ -20,10 +20,14 @@ pub fn setup_cargo() {
         );
     }
 
-    // Additionally, we also need 'rustfmt nightly', as we use experimental options.
-    // So let's install the '$RUST_NIGHTLY_VERSION' toolchain along with the 'rustfmt' component.
+    // Additionally, we also need the following nightly components:
+    //
+    // - 'rustfmt' as we use experimental options.
+    // - 'rust-docs' for the '--json' output to document the public API.
+    //
+    // So let's install the '$RUST_NIGHTLY_VERSION' toolchain along with these components.
     rustup_install_toolchain(env!("RUST_NIGHTLY_VERSION"));
-    rustup_add_components(env!("RUST_NIGHTLY_VERSION"), ["rustfmt"]);
+    rustup_add_components(env!("RUST_NIGHTLY_VERSION"), ["rustfmt", "rust-docs"]);
 
     // Make sure we have the latest dependencies:
     run_cargo_fetch();

crates/infra/utils/Cargo.toml

@@ -20,9 +20,17 @@ semver = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 similar-asserts = { workspace = true }
+strum = { workspace = true }
+strum_macros = { workspace = true }
 tera = { workspace = true }
 toml = { workspace = true }
 url = { workspace = true }
 
+[dev-dependencies]
+anyhow = { workspace = true }
+public-api = { workspace = true }
+rayon = { workspace = true }
+rustdoc-json = { workspace = true }
+
 [lints]
 workspace = true

crates/infra/utils/src/cargo/mod.rs

@@ -1,4 +1,6 @@
 mod manifest;
+mod public_api;
 mod workspace;
 
-pub use workspace::*;
+pub use public_api::UserFacingCrate;
+pub use workspace::{CargoWorkspace, CargoWorkspaceCommands};

crates/infra/utils/src/cargo/public_api.rs

@@ -0,0 +1,58 @@
+use strum_macros::{Display, EnumIter};
+
+#[derive(Clone, Copy, Debug, Display, EnumIter)]
+#[allow(non_camel_case_types)]
+pub enum UserFacingCrate {
+    // Sorted by dependency order (from dependencies to dependents):
+    metaslang_cst,
+    metaslang_graph_builder,
+    metaslang_bindings,
+    slang_solidity,
+    slang_solidity_cli,
+}
+
+#[cfg(test)]
+mod public_api_snapshots {
+    use anyhow::Result;
+    use rayon::iter::{ParallelBridge, ParallelIterator};
+    use strum::IntoEnumIterator;
+
+    use crate::cargo::{CargoWorkspace, UserFacingCrate};
+    use crate::codegen::CodegenFileSystem;
+
+    #[test]
+    fn public_api_snapshots() {
+        UserFacingCrate::iter()
+            .filter(|&crate_name| has_library_target(crate_name))
+            .par_bridge()
+            .for_each(|crate_name| generate_public_api(crate_name).unwrap());
+    }
+
+    fn generate_public_api(crate_name: UserFacingCrate) -> Result<()> {
+        let crate_dir = CargoWorkspace::locate_source_crate(crate_name.to_string())?;
+
+        let rustdoc_json = rustdoc_json::Builder::default()
+            .manifest_path(crate_dir.join("Cargo.toml"))
+            .all_features(true)
+            .toolchain(env!("RUST_NIGHTLY_VERSION"))
+            .build()?;
+
+        let public_api = public_api::Builder::from_rustdoc_json(rustdoc_json).build()?;
+
+        let output_path = crate_dir.join("generated/public_api.txt");
+
+        let mut fs = CodegenFileSystem::new(&crate_dir)?;
+
+        fs.write_file(output_path, public_api.to_string())
+    }
+
+    fn has_library_target(crate_name: UserFacingCrate) -> bool {
+        match crate_name {
+            UserFacingCrate::metaslang_cst => true,
+            UserFacingCrate::metaslang_graph_builder => true,
+            UserFacingCrate::metaslang_bindings => true,
+            UserFacingCrate::slang_solidity => true,
+            UserFacingCrate::slang_solidity_cli => false,
+        }
+    }
+}