Merge rust-bitcoin#3804: Introduce cargo-mutants workflow

bfba2a8 Kill remaining mutants (Shing Him Ng)
871fa08 Fix typo in serde docs (Shing Him Ng)
462c7a1 Add weekly cargo-mutants workflow (Shing Him Ng)

Pull request description:

  This PR introduces `cargo-mutants` via a Github weekly workflow, similar to how the formatter job runs. It can also be updated to run against [incremental changes in a PR](https://mutants.rs/pr-diff.html) or to create an issues that list the new mutants. To address rust-bitcoin#3796, I've configured it to only run in `units` for now since that's nearing 1.0.

  Here's a [sample run](https://github.com/shinghim/rust-bitcoin/actions/runs/12457984710) i did in my fork, if anyone would like to see what's in the `mutants-out` artifact that gets generated.

ACKs for top commit:
  tcharding:
    ACK bfba2a8
  apoelstra:
    ACK bfba2a8; successfully ran local tests

Tree-SHA512: e4a44b6f5121e4238c1c3576616f551f4f43349cf5fd5ac1d6331f958a4458753a55519bdafc16965cb2e67201ef6c91b188c79ffcc222f780c421df9a701063

Author: apoelstra

.cargo/mutants.toml

@@ -0,0 +1,27 @@
+additional_cargo_args = ["--all-features"]
+examine_globs = ["units/src/**/*.rs"]
+exclude_globs = [
+    "units/src/amount/verification.rs" # kani tests
+]
+exclude_re = [
+    "impl Debug",
+    "impl Arbitrary",
+    "impl Display",
+    ".*Error",
+    # --------------------------------------------Crate-specific exclusions--------------------------------------------
+    # Units
+    # src/amount/mod.rs
+    "parse_signed_to_satoshi", # Can't kill all mutants since there is no denomination smaller than Satoshi
+    "fmt_satoshi_in", # Related to formatting/display
+    "dec_width", # Replacing num /= 10 with num %=10 in a loop causes a timeout due to infinite loop
+    # src/fee_rate/serde.rs
+    "as_sat_per_kwu::opt::deserialize::<impl Visitor for VisitOpt>.*", # Replaces return value with Ok(Default::default()), which is the same as Ok(None)
+    "as_sat_per_vb_floor::opt::deserialize::<impl Visitor for VisitOpt>.*", # Replaces return value with Ok(Default::default()), which is the same as Ok(None)
+    "as_sat_per_vb_ceil::opt::deserialize::<impl Visitor for VisitOpt>.*", # Replaces return value with Ok(Default::default()), which is the same as Ok(None)
+    # src/amount/serde.rs
+    "as_sat::opt::deserialize::<impl Visitor for VisitOptAmt<X>>.*", # Replaces return value with Ok(Default::default()), which is the same as Ok(None)
+    "as_btc::opt::deserialize::<impl Visitor for VisitOptAmt<X>>.*", # Replaces return value with Ok(Default::default()), which is the same as Ok(None)
+    "as_str::opt::deserialize::<impl Visitor for VisitOptAmt<X>>.*", # Replaces return value with Ok(Default::default()), which is the same as Ok(None)
+    # src/locktime/relative.rs
+    "Time::to_consensus_u32" # It will replace | with ^, which will return the same value since the XOR is always taken against the u16 and an all-zero bitmask
+]

.github/workflows/cron-weekly-cargo-mutants.yml

@@ -0,0 +1,41 @@
+name: Weekly cargo-mutants
+on:
+  schedule:
+    - cron: "0 0 * * 0" # runs weekly on Sunday at 00:00
+  workflow_dispatch: # allows manual triggering
+jobs:
+  cargo-mutants:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-mutants
+      - run: cargo mutants --in-place --no-shuffle
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: mutants.out
+          path: mutants.out
+      - name: Check for new mutants
+        if: always()
+        run: |
+          if [ -s mutants.out/missed.txt ]; then
+            echo "New missed mutants found"
+            gh issue create \
+            --title "New Mutants Found" \
+            --body "$(cat <<EOF
+          Displaying up to the first 10 mutants:
+
+          $(head -n 10 mutants.out/missed.txt)
+
+          For the complete list, please check the [mutants.out artifact](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}).
+          EOF
+          )"
+            echo "create_issue=true" >> $GITHUB_ENV
+          else
+            echo "No new mutants found"
+            echo "create_issue=false" >> $GITHUB_ENV
+          fi
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -14,6 +14,7 @@ hashes/target
 
 # Test artifacts
 bitcoin/dep_test
+mutants.out*
 
 # Fuzz artifacts
 hfuzz_target

units/src/amount/tests.rs

@@ -1014,10 +1014,12 @@ fn sum_amounts() {
     assert_eq!([].iter().sum::<SignedAmount>(), SignedAmount::ZERO);
 
     let amounts = [sat(42), sat(1337), sat(21)];
+    assert_eq!(amounts.iter().sum::<Amount>(), sat(1400));
     let sum = amounts.into_iter().sum::<Amount>();
     assert_eq!(sum, sat(1400));
 
     let amounts = [ssat(-42), ssat(1337), ssat(21)];
+    assert_eq!(amounts.iter().sum::<SignedAmount>(), ssat(1316));
     let sum = amounts.into_iter().sum::<SignedAmount>();
     assert_eq!(sum, ssat(1316));
 }

units/src/fee_rate/mod.rs

@@ -69,9 +69,6 @@ impl FeeRate {
     pub const fn to_sat_per_vb_floor(self) -> u64 { self.0 / (1000 / 4) }
 
     /// Converts to sat/vB rounding up.
-    /// TODO: cargo-mutants will try to replace - with /, which results in 1000 / 4 / 1 which is also 250.
-    /// Since we're addressing the mutants before introducing the cargo-mutants workflow, come back later
-    /// and skip this function in the mutants.toml config file
     pub const fn to_sat_per_vb_ceil(self) -> u64 { (self.0 + (1000 / 4 - 1)) / (1000 / 4) }
 
     /// Checked multiplication.

units/src/fee_rate/serde.rs

@@ -171,7 +171,7 @@ pub mod as_sat_per_vb_ceil {
     //! Serialize and deserialize [`FeeRate`] denominated in satoshis per virtual byte.
     //!
     //! When serializing use ceil division to convert per kwu to per virtual byte.
-    //! Use with `#[serde(with = "fee_rate::serde::as_sat_per_vb")]`.
+    //! Use with `#[serde(with = "fee_rate::serde::as_sat_per_vb_ceil")]`.
 
     use serde::{Deserialize, Deserializer, Serialize, Serializer};
 

units/src/locktime/relative.rs

@@ -116,8 +116,6 @@ impl Time {
 
     /// Returns the `u32` value used to encode this locktime in an nSequence field or
     /// argument to `OP_CHECKSEQUENCEVERIFY`.
-    /// TODO: Skip this in cargo-mutants. It will replace | with ^, which will return the same
-    /// value since the XOR is always taken against the u16 and an all-zero bitmask
     #[inline]
     pub const fn to_consensus_u32(self) -> u32 {
         (1u32 << 22) | self.0 as u32 // cast safety: u32 is wider than u16 on all architectures