cleanup: CI / dependabot / tests (#1)

Author: ahl

.github/dependabot.yml

@@ -0,0 +1,14 @@
+#
+# Dependabot configuration file
+#
+
+version: 2
+updates:
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/release.yml

@@ -13,6 +13,7 @@ permissions: {}
 jobs:
   create-release:
     runs-on: ubuntu-latest
+    if: github.repository_owner == 'oxidecomputer'
     permissions:
       # for creating the GitHub release
       contents: write
@@ -21,8 +22,16 @@ jobs:
         with:
           persist-credentials: false
       - name: Install Rust
-        uses: dtolnay/rust-toolchain@stable
-      - run: cargo publish -p codespace
+        uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+      - name: Check that the tag matches the crate version
+        run: |
+          version=$(cargo metadata --no-deps --format-version 1 \
+            | jq -r '.packages[0].version')
+          if [ "$GITHUB_REF_NAME" != "v$version" ]; then
+            echo "tag $GITHUB_REF_NAME does not match crate version $version" >&2
+            exit 1
+          fi
+      - run: cargo publish -p codespace --locked
         env:
           CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
       - uses: taiki-e/create-gh-release-action@72d65cee1f8033ef0c8b5d79eaf0c45c7c578ce3 # v1

.github/workflows/rust.yml

@@ -8,26 +8,62 @@ on:
     branches: [ main ]
   pull_request:
     branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
   check-style:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4
     - name: Report cargo version
       run: cargo --version
     - name: Report rustfmt version
       run: cargo fmt -- --version
     - name: Check style
       run: cargo fmt -- --check
 
+  clippy:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4
+    - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+    - name: Report clippy version
+      run: cargo clippy --version
+    - name: Run clippy
+      run: cargo clippy --locked --all-targets -- -D warnings
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4
+    - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+    - name: Build documentation
+      run: cargo doc --locked --no-deps
+      env:
+        RUSTDOCFLAGS: -D warnings
+
   build-and-test:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
         os: [ ubuntu-latest, windows-latest, macos-latest ]
+        # 1.97 is the MSRV
+        rust-version: [ stable, "1.97" ]
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4
+    - uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+      with:
+        toolchain: ${{ matrix.rust-version }}
+    - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+    - name: Report rustc version
+      run: rustc --version
     - name: Build
       run: cargo build --locked --tests --verbose
     - name: Run tests

Cargo.toml

@@ -2,9 +2,11 @@
 name = "codespace"
 version = "0.0.1-alpha.1"
 edition = "2021"
+rust-version = "1.97"
 license = "Apache-2.0"
 repository = "https://github.com/oxidecomputer/codespace"
-description = "A structured container for generated Rust code"
+description = "Structural scratch space for generated Rust code"
+exclude = [".github", "rust-toolchain.toml"]
 
 [dependencies]
 proc-macro2 = "1.0.104"

README.md

@@ -2,7 +2,7 @@
 
 [![codespace on crates.io](https://img.shields.io/crates/v/codespace)](https://crates.io/crates/codespace)
 [![Documentation (latest release)](https://img.shields.io/badge/docs-latest%20version-brightgreen.svg)](https://docs.rs/codespace)
-[![License](https://img.shields.io/badge/license-Apache-green.svg)](LICENSE)
+[![License](https://img.shields.io/badge/license-Apache-green.svg)](https://github.com/oxidecomputer/codespace/blob/main/LICENSE)
 
 Structural scratch space for generated Rust code
 
@@ -54,5 +54,5 @@ details.
 
 ## Notes
 
-- Pre-publication; API unstable.
+- Early alpha; API unstable.
 - Part of the typify/progenitor code-generation stack.

src/lib.rs

@@ -46,6 +46,9 @@
 //! Within each [`Mod`], items are emitted in sort-key order and submodules
 //! in alphabetical order by name.
 
+#![forbid(unsafe_code)]
+#![warn(missing_docs, missing_debug_implementations)]
+
 use std::{
     collections::{btree_map::Entry, BTreeMap},
     path::{Path, PathBuf},
@@ -67,7 +70,7 @@ fn validate_mod_name(name: &str, full: &str) {
     // syn must accept `gen` (an identifier before edition 2024), but our
     // generated code may land in a 2024 crate, so we reject it ourselves.
     if name == "gen" {
-        panic!("module name {:?} (in {:?}) is a Rust keyword", name, full);
+        panic!("module name {name:?} (in {full:?}) is a Rust keyword");
     }
     if !name.starts_with("r#") && syn::parse_str::<syn::Ident>(name).is_ok() {
         return;
@@ -84,12 +87,11 @@ fn validate_mod_name(name: &str, full: &str) {
             )
         });
     if is_keyword {
-        panic!("module name {:?} (in {:?}) is a Rust keyword", name, full);
+        panic!("module name {name:?} (in {full:?}) is a Rust keyword");
     }
     panic!(
-        "module name {:?} (in {:?}) is not a valid Rust identifier \
+        "module name {name:?} (in {full:?}) is not a valid Rust identifier \
          (raw identifiers are not supported)",
-        name, full,
     );
 }
 
@@ -505,7 +507,7 @@ impl Mod {
                 #vis mod #ident;
             });
             let (file, child_dir) = if m.mods.is_empty() {
-                (dir.join(format!("{}.rs", name)), dir.to_path_buf())
+                (dir.join(format!("{name}.rs")), dir.to_path_buf())
             } else {
                 let child_dir = dir.join(&name);
                 (child_dir.join("mod.rs"), child_dir)
@@ -622,7 +624,7 @@ mod tests {
     }
 
     #[test]
-    #[should_panic]
+    #[should_panic(expected = "is not a valid Rust identifier")]
     fn invalid_mod_name_panics() {
         let mut cs = Codespace::default();
         cs.add_item("not-valid-ident::key", quote! {});
@@ -671,7 +673,7 @@ mod tests {
     }
 
     #[test]
-    #[should_panic]
+    #[should_panic(expected = "is not a valid Rust identifier")]
     fn get_mod_invalid_ident_panics() {
         let mut cs = Codespace::default();
         cs.get_root_mod().get_mod("not-valid");
@@ -751,9 +753,9 @@ mod tests {
         m.add_attr(quote! { allow(dead_code) });
         m.add_item("f", quote! { pub fn f() {} });
         let out = no_ws(&cs.into_stream().to_string());
-        assert!(out.contains(r##"#[doc="Helperfunctions."]"##));
+        assert!(out.contains(r#"#[doc="Helperfunctions."]"#));
         // Metadata appears immediately before the mod, in outer form.
-        assert!(out.contains(r##"#[allow(dead_code)]pubmodhelpers{"##));
+        assert!(out.contains(r#"#[allow(dead_code)]pubmodhelpers{"#));
         assert!(!out.contains("#!"));
     }
 
@@ -815,11 +817,56 @@ mod tests {
         let mut cs = Codespace::default();
         cs.get_root_mod().add_mod("m", a);
         let out = no_ws(&cs.into_stream().to_string());
-        assert!(out.contains(r##"#[doc="First."]#[doc=""]#[doc="Second."]"##));
+        assert!(out.contains(r#"#[doc="First."]#[doc=""]#[doc="Second."]"#));
         assert!(out.contains("#[allow(dead_code)]#[allow(unused)]"));
         assert!(out.contains("pub(crate)modm"));
     }
 
+    #[test]
+    fn replace_mod_clobbers_existing() {
+        let mut root = Mod::default();
+        // First insertion: nothing to return.
+        let mut m1 = Mod::default();
+        m1.add_item("f", quote! { pub fn f() {} });
+        assert!(root.replace_mod("client", m1).is_none());
+        // Replacement returns the previous module and clobbers it--no
+        // merging, in contrast to add_mod.
+        let mut m2 = Mod::default();
+        m2.add_item("g", quote! { pub fn g() {} });
+        let prev = root.replace_mod("client", m2).unwrap();
+        assert!(prev.items.contains_key("f"));
+        let mut cs = Codespace::default();
+        *cs.get_root_mod() = root;
+        let out = cs.into_stream().to_string();
+        assert_eq!(out.matches("mod client").count(), 1);
+        assert!(out.contains("fn g"));
+        assert!(!out.contains("fn f"));
+    }
+
+    #[test]
+    #[should_panic(expected = "is a Rust keyword")]
+    fn replace_mod_keyword_panics() {
+        let mut root = Mod::default();
+        root.replace_mod("type", Mod::default());
+    }
+
+    #[test]
+    fn into_root_mod_mounts_in_another_codespace() {
+        // Generate a subsystem in its own Codespace, then mount it as a
+        // submodule of a larger one.
+        let mut inner = Codespace::default();
+        inner.add_item("Foo", quote! { pub struct Foo; });
+        inner.add_item("defaults::f", quote! { pub fn f() {} });
+        let mut outer = Codespace::default();
+        outer.add_item("Bar", quote! { pub struct Bar; });
+        outer.add_mod("subsystem", inner.into_root_mod());
+        let out = no_ws(&outer.into_stream().to_string());
+        assert!(out.contains("pubstructBar"));
+        assert!(out.contains("pubmodsubsystem{"));
+        assert!(out.contains("pubstructFoo"));
+        assert!(out.contains("pubmoddefaults{"));
+    }
+
     #[test]
     fn add_mod_inserts_new() {
         let mut cs = Codespace::default();
@@ -912,14 +959,35 @@ mod tests {
         // Docs and attrs are outer, at the declaration site, immediately
         // before the visibility and declaration.
         assert!(
-            lib.contains(r##"#[doc="Helperfunctions."]#[allow(dead_code)]pub(crate)modhelpers;"##)
+            lib.contains(r#"#[doc="Helperfunctions."]#[allow(dead_code)]pub(crate)modhelpers;"#)
         );
         // Nothing of the metadata leaks into the child file.
         let helpers = no_ws(&files[Path::new("helpers.rs")].to_string());
         assert!(!helpers.contains("doc"));
         assert!(!helpers.contains("allow"));
     }
 
+    #[test]
+    fn into_files_non_leaf_decl_carries_metadata() {
+        // Like into_files_decl_carries_metadata, but for a module with
+        // children: metadata belongs on the declaration in the parent, not
+        // in the child's mod.rs.
+        let mut cs = Codespace::default();
+        let m = cs.get_root_mod().get_mod("outer");
+        m.set_visibility(Visibility::Private);
+        m.add_docs("Outer module.");
+        m.add_attr(quote! { allow(dead_code) });
+        m.get_mod("inner").add_item("f", quote! { pub fn f() {} });
+        let files = cs.into_files();
+        let lib = no_ws(&files[Path::new("lib.rs")].to_string());
+        assert!(lib.contains(r#"#[doc="Outermodule."]#[allow(dead_code)]modouter;"#));
+        assert!(!lib.contains("pubmodouter"));
+        // The child's own file holds only its contents and its child's
+        // declaration.
+        let outer = no_ws(&files[Path::new("outer/mod.rs")].to_string());
+        assert_eq!(outer, "pubmodinner;");
+    }
+
     #[test]
     fn into_files_root_meta_is_inner() {
         let mut cs = Codespace::default();
@@ -928,7 +996,7 @@ mod tests {
         cs.add_item("Foo", quote! { pub struct Foo; });
         let files = cs.into_files();
         let lib = no_ws(&files[Path::new("lib.rs")].to_string());
-        assert!(lib.starts_with(r##"#![doc="Generatedcode."]#![allow(clippy::all)]"##));
+        assert!(lib.starts_with(r#"#![doc="Generatedcode."]#![allow(clippy::all)]"#));
     }
 
     #[test]
@@ -971,7 +1039,7 @@ mod tests {
         // Lines within one call stay in one paragraph; a blank doc line
         // separates calls.
         assert!(out.contains(
-            r##"#[doc="Firstparagraph."]#[doc="Stillthefirst."]#[doc=""]#[doc="Secondparagraph."]"##
+            r#"#[doc="Firstparagraph."]#[doc="Stillthefirst."]#[doc=""]#[doc="Secondparagraph."]"#
         ));
     }
 
@@ -982,9 +1050,8 @@ mod tests {
         cs.get_root_mod().add_attr(quote! { allow(clippy::all) });
         cs.add_item("Foo", quote! { pub struct Foo; });
         let out = no_ws(&cs.into_stream().to_string());
-        assert!(out.starts_with(
-            r##"#![doc="Generatedcode."]#![doc="Donotedit."]#![allow(clippy::all)]"##
-        ));
+        assert!(out
+            .starts_with(r#"#![doc="Generatedcode."]#![doc="Donotedit."]#![allow(clippy::all)]"#));
         assert!(out.contains("pubstructFoo"));
     }
 }