Remove ^= as mutation for |= and &= operators (#556)

## Problem

When mutating bitwise assignment operators, cargo-mutants was suggesting
replacing `|=` with `^=` (and `&=` with `^=`). However, this mutation is
uninformative for the common pattern of accumulating bits into a bitmap
that starts from zero:

```rust
let base_ix = self.text.len();
self.chars |= slice.chars << base_ix;
self.chars_utf16 |= slice.chars_utf16 << base_ix;
```

In this code (from Zed's `crates/rope/src/chunk.rs`), when accumulating
new set bits into a bitmap that's initially zeros, `|=` and `^=` produce
identical results. The mutation doesn't actually test anything
different.

## Solution

Changed the mutation patterns for bitwise assignment operators:

- `&=` now only mutates to `|=` (removed `^=`)
- `|=` now only mutates to `&=` (removed `^=`)
- `^=` still mutates to both `|=` and `&=` (unchanged)

This makes the mutations more meaningful by ensuring they actually
change the behavior in typical usage patterns.

## Changes

- Updated mutation logic in `src/visit.rs`
- Updated documentation in `book/src/mutants.md` with explicit entries
for bitwise assignment operators
- Added changelog entry to `NEWS.md`
- Updated test expectations in `mutate_assign_ops` test

Author: sourcefrog

NEWS.md

@@ -8,6 +8,8 @@
 
 - New: `start_time` and `end_time` fields in `outcomes.json`.
 
+- Changed: The bitwise assignment operators `&=` and `|=` are no longer mutated to `^=`. In code that accumulates bits into a bitmap starting from zero (e.g., `bitmap |= new_bits`), `|=` and `^=` produce the same result, making such mutations uninformative.
+
 ## 25.3.1 2025-08-10
 
 - Fixed: cargo-mutants' own tests were failing on nightly due to a change in the format of messages emitted by tests.

book/src/mutants.md

@@ -83,12 +83,17 @@ like `a == 0`.
 | `&`      | `\|`,`^`           |
 | `\|`     | `&`, `^`           |
 | `^`      | `&`, `\|`          |
-| `+=` and similar assignments | assignment corresponding to the line above |
+| `&=`     | `\|=`              |
+| `\|=`    | `&=`               |
+| `^=`     | `\|=`, `&=`        |
+| `+=`, `-=`, `*=`, `/=`, `%=`, `<<=`, `>>=` | assignment corresponding to the operator above |
 
 Equality operators are not currently replaced with comparisons like `<` or `<=`
 because they are
 too prone to generate false positives, for example when unsigned integers are compared to 0.
 
+The bitwise assignment operators `&=` and `|=` are not mutated to `^=` because in code that accumulates bits (e.g., `bitmap |= new_bits`), `|=` and `^=` produce the same result when starting from zero, making such mutations uninformative.
+
 ## Unary operators
 
 Unary operators are deleted in expressions like `-a` and `!a`.

src/visit.rs

@@ -591,9 +591,9 @@ impl<'ast> Visit<'ast> for DiscoveryVisitor<'_> {
             BinOp::Shr(_) => vec![quote! {<<}],
             BinOp::ShrAssign(_) => vec![quote! {<<=}],
             BinOp::BitAnd(_) => vec![quote! {|}, quote! {^}],
-            BinOp::BitAndAssign(_) => vec![quote! {|=}, quote! {^=}],
+            BinOp::BitAndAssign(_) => vec![quote! {|=}],
             BinOp::BitOr(_) => vec![quote! {&}, quote! {^}],
-            BinOp::BitOrAssign(_) => vec![quote! {&=}, quote! {^=}],
+            BinOp::BitOrAssign(_) => vec![quote! {&=}],
             BinOp::BitXor(_) => vec![quote! {|}, quote! {&}],
             BinOp::BitXorAssign(_) => vec![quote! {|=}, quote! {&=}],
             _ => {
@@ -1389,14 +1389,8 @@ mod test {
             mutate_expr("a /= b"),
             &["replace /= with %=", "replace /= with *="]
         );
-        assert_eq!(
-            mutate_expr("a &= b"),
-            &["replace &= with |=", "replace &= with ^="]
-        );
-        assert_eq!(
-            mutate_expr("a |= b"),
-            &["replace |= with &=", "replace |= with ^="]
-        );
+        assert_eq!(mutate_expr("a &= b"), &["replace &= with |="]);
+        assert_eq!(mutate_expr("a |= b"), &["replace |= with &="]);
         assert_eq!(
             mutate_expr("a ^= b"),
             &["replace ^= with |=", "replace ^= with &="]