feat(fuzz): add cargo-fuzz targets + CI, fix RangeExpr overflow panics

Adds a coverage-guided libFuzzer suite (via cargo-fuzz) over the crates that
parse or evaluate untrusted input, and a GitHub Actions workflow that smoke-
fuzzes every target on PRs/pushes and runs a deeper corpus-accumulating pass on
a nightly schedule.

Motivation: the quality-evaluation reports in reports/ kept re-discovering the
same class of defect by hand — arithmetic overflow and char-boundary panics
reachable from attacker-controlled expression text, templates, and manifests
(e.g. the expr report's exploratory findings). Encoding that class as a
permanent executable check stops it from being re-litigated every review cycle.

Six targets, each asserting "any input returns Ok or Err — never panic, abort,
or hang":
  - expr_parse       ParsedExpression::new
  - expr_evaluate    parse + evaluate against a fuzzer-seeded symbol table
  - range_expr       RangeExpr::from_str + len/get/iter
  - format_string    FormatString::new + resolve_string_with
  - model_decode     document_string_to_object + decode_{job,environment}_template
  - snapshot_decode  decode_manifest + Manifest::validate

The fuzz crate is outside the root workspace (its own empty [workspace] table)
so the stable build/test/clippy/MSRV jobs are untouched; it builds only under a
pinned nightly with AddressSanitizer, overflow-checks, and debug-assertions on.
Small curated seed corpora (mined from the crates' own tests and sample
templates) live in fuzz/seeds/ and are committed; the evolving runtime corpus
and crash artifacts are git-ignored and cached by CI.

The range_expr target immediately reproduced two live overflow panics (expr
report finding X1 and a multi-chunk variant), both fixed here at the root:
  - IntRange::new: normalization arithmetic ((end-start)/step+1 and the
    endpoint computation) now uses checked ops and returns a parse error for
    endpoints whose element count or span overflows i64 (e.g.
    "0-9223372036854775807", full i64-span ranges).
  - RangeExpr merge: the adjacency test last.end + r.step now uses checked_add,
    treating overflow as "not adjacent" instead of panicking/wrapping.
Adds a huge_span_does_not_overflow regression test. All 3356 existing
openjd-expr tests still pass; clippy -D warnings is clean.

Signed-off-by: Stephen Crowe <6042774+crowecawcaw@users.noreply.github.com>

Author: crowecawcaw

.github/workflows/fuzz.yml

@@ -0,0 +1,95 @@
+name: Fuzz
+
+# Smoke-fuzz every fuzz target on pull requests and on merges to main. The
+# run is short and time-boxed per target so it gates without slowing the merge
+# queue. Any panic, abort, overflow, or char-boundary slice in a fuzzed entry
+# point fails the job. Coverage plateaus within about a minute per target once
+# seeded, so a longer run buys little here; deeper campaigns are left to manual
+# local runs (see fuzz/README.md).
+#
+# The fuzz crate (fuzz/) is deliberately outside the root workspace and builds
+# only with a nightly toolchain under AddressSanitizer, so it lives in its own
+# workflow rather than the stable CI matrix.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main, release, "patch_*"]
+  workflow_dispatch:
+
+concurrency:
+  group: fuzz-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  CARGO_INCREMENTAL: 0
+  CARGO_NET_RETRY: 10
+  RUSTUP_MAX_RETRIES: 10
+  RUST_BACKTRACE: 1
+  # Per-target smoke budget, in seconds. Six targets run sequentially in one
+  # job after a single build.
+  FUZZ_SECONDS: 60
+
+jobs:
+  fuzz:
+    name: Fuzz
+    # libFuzzer + cargo-fuzz's sanitizer build is best supported on Linux.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      # cargo-fuzz requires a nightly toolchain (sanitizer -Z flags). Pin the
+      # nightly so a bad nightly (e.g. an ASan codegen ICE) can't randomly break
+      # the fuzz job; bump this date deliberately.
+      - name: Install Rust nightly
+        run: |
+          rustup toolchain install nightly-2026-05-15 --profile minimal --component rust-src
+          rustup override set nightly-2026-05-15
+
+      - name: Compute rustc hash
+        id: rustc
+        run: echo "hash=$(rustc +nightly-2026-05-15 --version --verbose | sha256sum | cut -c1-16)" >> "$GITHUB_OUTPUT"
+
+      - name: Restore cargo + fuzz cache
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry/index
+            ~/.cargo/registry/cache
+            ~/.cargo/git/db
+            ~/.cargo/bin/cargo-fuzz
+            fuzz/target
+          key: fuzz-${{ steps.rustc.outputs.hash }}-${{ hashFiles('**/Cargo.lock', 'fuzz/Cargo.toml') }}
+          restore-keys: |
+            fuzz-${{ steps.rustc.outputs.hash }}-
+            fuzz-
+
+      - name: Install cargo-fuzz
+        run: which cargo-fuzz || cargo install cargo-fuzz --locked --version ^0.13
+
+      # One build pass produces all six target binaries.
+      - name: Build fuzz targets
+        run: cargo fuzz build
+
+      # Loop over every target, each seeded with its committed corpus in
+      # fuzz/seeds/<target>. A crash in any target fails the whole job (set -e).
+      - name: Run fuzz targets
+        run: |
+          set -euo pipefail
+          for target in expr_parse expr_evaluate range_expr format_string model_decode snapshot_decode; do
+            echo "::group::fuzz $target (${FUZZ_SECONDS}s)"
+            cargo fuzz run "$target" "fuzz/seeds/$target" \
+              -- -max_total_time="$FUZZ_SECONDS" -timeout=25 -rss_limit_mb=4096
+            echo "::endgroup::"
+          done
+
+      # If any target produced a crash artifact, surface it so the failure is
+      # actionable from the run page instead of just a red X.
+      - name: Upload crash artifacts
+        if: failure()
+        uses: actions/upload-artifact@v7
+        with:
+          name: fuzz-artifacts
+          path: fuzz/artifacts
+          if-no-files-found: ignore

crates/openjd-expr/src/range_expr.rs

@@ -116,19 +116,27 @@ impl IntRange {
                 "Range: an ascending range must have a positive step",
             ));
         }
+        // All of the normalization arithmetic below can overflow i64 for
+        // extreme but individually-valid endpoints — e.g. `0-9223372036854775807`
+        // makes `count = (end - start) / step + 1` exceed i64::MAX, and a span
+        // from i64::MIN to i64::MAX overflows the `end - start` subtraction
+        // itself. These inputs are reachable from untrusted range-expression
+        // text, so every step uses checked arithmetic and reports a clear
+        // parse error instead of panicking (debug) or wrapping (release).
         if step < 0 {
             // Normalize descending to ascending form (matching Python _IntRange)
-            let count = ((start - end) / (-step)) + 1;
-            let last = start + (count - 1) * step; // smallest value
+            let count = Self::checked_count(start, end, -step)?;
+            // last (smallest value) = start + (count - 1) * step, step < 0
+            let last = Self::checked_endpoint(start, count, step)?;
             Ok(Self {
                 start: last,
                 end: start,
                 step: -step,
             })
         } else {
             // Normalize end to actual last value in the range
-            let count = (end - start) / step + 1;
-            let actual_end = start + (count - 1) * step;
+            let count = Self::checked_count(end, start, step)?;
+            let actual_end = Self::checked_endpoint(start, count, step)?;
             Ok(Self {
                 start,
                 end: actual_end,
@@ -137,10 +145,37 @@ impl IntRange {
         }
     }
 
+    /// Number of elements in a normalized range with the given `hi >= lo` and
+    /// `abs_step > 0`, i.e. `(hi - lo) / abs_step + 1`, using checked
+    /// arithmetic. Returns a parse error if the span or the `+ 1` overflows.
+    fn checked_count(hi: i64, lo: i64, abs_step: i64) -> Result<i64, ExpressionError> {
+        hi.checked_sub(lo)
+            .and_then(|span| span.checked_div(abs_step))
+            .and_then(|q| q.checked_add(1))
+            .ok_or_else(Self::too_large_error)
+    }
+
+    /// Compute `base + (count - 1) * step` with checked arithmetic. Returns a
+    /// parse error on overflow.
+    fn checked_endpoint(base: i64, count: i64, step: i64) -> Result<i64, ExpressionError> {
+        count
+            .checked_sub(1)
+            .and_then(|n| n.checked_mul(step))
+            .and_then(|offset| base.checked_add(offset))
+            .ok_or_else(Self::too_large_error)
+    }
+
+    fn too_large_error() -> ExpressionError {
+        ExpressionError::parse_error("Range: the number of elements is too large to represent")
+    }
+
     /// Number of integers in this range.
     pub fn len(&self) -> usize {
-        // After normalization, start <= end and step > 0 always
-        ((self.end - self.start) / self.step + 1) as usize
+        // After normalization, start <= end and step > 0 always. The span and
+        // count were bounds-checked in `new`, so the length fits in i64; clamp
+        // into usize (which is >= 64 bits on supported targets) defensively.
+        let count = (self.end - self.start) / self.step + 1;
+        usize::try_from(count).unwrap_or(usize::MAX)
     }
 
     /// Returns `true` if the range contains no elements.
@@ -320,7 +355,16 @@ impl RangeExpr {
         let mut merged = vec![ranges[0].clone()];
         for r in &ranges[1..] {
             let last = merged.last().unwrap();
-            if last.step == r.step && last.end + r.step == r.start {
+            // `last.end + r.step` can overflow i64 when `last.end` is near the
+            // i64 bounds (reachable from untrusted multi-chunk range text). An
+            // overflowing sum can never equal `r.start` (also an i64), so treat
+            // overflow as "not adjacent" rather than panicking/wrapping.
+            let adjacent = last.step == r.step
+                && last
+                    .end
+                    .checked_add(r.step)
+                    .is_some_and(|next| next == r.start);
+            if adjacent {
                 let new_end = r.end;
                 let last_start = last.start;
                 let step = last.step;
@@ -779,6 +823,22 @@ mod tests {
         assert!("5-1".parse::<RangeExpr>().is_err());
     }
 
+    // Regression: individually-valid endpoints whose element count or last
+    // element overflows i64 must be rejected with a parse error, not panic
+    // (debug) or wrap (release). Found by the `range_expr` fuzz target; see
+    // the expr quality report's exploratory finding X1.
+    #[test]
+    fn huge_span_does_not_overflow() {
+        // count = (end - start)/step + 1 overflows i64
+        assert!("0-9223372036854775807".parse::<RangeExpr>().is_err());
+        // full i64 span overflows the (end - start) subtraction itself
+        assert!("-9223372036854775808-9223372036854775807"
+            .parse::<RangeExpr>()
+            .is_err());
+        // descending form with a huge span
+        assert!("9223372036854775807-0:-1".parse::<RangeExpr>().is_err());
+    }
+
     // ── slice() tests ──
 
     #[test]

fuzz/.gitignore

@@ -0,0 +1,4 @@
+target
+corpus
+artifacts
+coverage