ci: enforce the no-panic rule with a script and required CI step

Adds scripts/verify-no-panic-apis.sh and runs it in the check job. Production
contract code must return typed errors; a panic in a deployed contract is an
untyped failure a caller cannot handle.

This converts one rule from enforced-in-review to enforced-mechanically, which is
the same alignment the last commit made in the other direction by correcting
claims about checks that did not exist. The difference is that this one now runs.

Scoping matches the rule rather than approximating it. The script reads each file
under src/ up to its first #[cfg(test)] marker, treats a file with no marker as
production code throughout, and does not examine tests/ at all. Comments and
string literals are stripped before matching, so prose in a doc comment and the
message inside .expect("...") are not mistaken for calls.

Verified in four directions before wiring: the current tree passes, a planted
.unwrap() above a cfg(test) marker is caught with the correct file and line, one
planted below it is ignored, and a panic! added to error.rs, which has no
cfg(test) block at all, is caught.

Banned in production: .unwrap(), .expect(, panic!, todo!, unimplemented!. The
failure message names the fix and points at requirements 5.1, CONTRIBUTING, and
ADR-015 for the test-code exception.

The reference deferred at B2 is now concrete in .agent/testing.md, and
requirements 5.1 records that its Rust items are mechanically enforced here.

Author: EmeditWeb

.agent/testing.md

@@ -73,9 +73,14 @@ failed. A bare `.expect("")` or an `unwrap` standing in for an assertion is not
 acceptable.
 
 Production code, meaning everything under `src/` outside a `#[cfg(test)]` block,
-remains bound by the no-panic rule. See ADR-015. The mechanical check enforcing
-it is scoped the same way: it scans each file under `src/` up to the first
-`#[cfg(test)]` marker and does not look at `tests/` at all.
+remains bound by the no-panic rule. See ADR-015.
+
+`scripts/verify-no-panic-apis.sh` enforces this and runs as a required CI step.
+It is scoped the same way the rule is: it reads each file under `src/` up to the
+first `#[cfg(test)]` marker, treats a file without one as production code
+throughout, and does not look at `tests/` at all. It strips comments and string
+literals before matching, so prose in a doc comment and the message inside
+`.expect("...")` do not register as calls. Run it locally with no arguments.
 
 ## One behavior per test
 

.github/workflows/ci.yml

@@ -70,6 +70,13 @@ jobs:
         if: steps.members.outputs.present == 'true'
         run: cargo clippy --workspace --all-targets -- -D warnings
 
+      # Production contract code must return typed errors rather than panic.
+      # The script scopes itself to src/ above each file's first #[cfg(test)],
+      # so test code keeps the ADR-015 expect exception.
+      - name: Verify no panicking APIs in production code
+        if: steps.members.outputs.present == 'true'
+        run: ./scripts/verify-no-panic-apis.sh
+
       - name: Test
         if: steps.members.outputs.present == 'true'
         run: cargo test --workspace

docs/requirements.md

@@ -426,6 +426,13 @@ Reinforcing the playbook's operating principles. These rules apply to every arti
 - No `unimplemented!()` (Rust)
 - No `panic("not implemented")` (Go)
 - No `throw new Error("TODO")` (TS)
+
+In `pulsar-core` the Rust items are enforced mechanically by
+`scripts/verify-no-panic-apis.sh`, a required CI step. It also covers `.unwrap()`,
+`.expect(`, `panic!`, and `todo!`, which CONTRIBUTING forbids in contract code for
+the same reason: a panic is an untyped failure a caller cannot handle. The check
+reads each file under `src/` up to its first `#[cfg(test)]` marker, so test code
+keeps the descriptive-message exception in ADR-015.
 - Every function commit is complete and testable at the moment it lands
 
 ### 5.2 No fabricated numbers

scripts/verify-no-panic-apis.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+#
+# Fails if production contract code uses an API that panics instead of returning
+# a typed error. A panic in a deployed contract is an untyped failure a caller
+# cannot handle, which is why requirements.md section 5.1 forbids the placeholder
+# forms and CONTRIBUTING forbids the rest.
+#
+# Scope: everything under a crate's src/ directory, up to the first #[cfg(test)]
+# marker in each file. Tests below that marker are exempt, and integration tests
+# under tests/ are not examined at all. Test code may use .expect("message") with
+# a descriptive message, per ADR-015: there the panic text is the diagnostic.
+#
+# Usage: scripts/verify-no-panic-apis.sh [src-dir ...]
+# Defaults to every contracts/*/src and crates/*/src directory that exists.
+
+set -euo pipefail
+
+BANNED_DESC=(
+    '.unwrap()'
+    '.expect('
+    'panic!'
+    'todo!'
+    'unimplemented!'
+)
+# Matched against code with comments and string literals already stripped.
+BANNED_RE='\.unwrap\(\)|\.expect\(|\bpanic!|\btodo!|\bunimplemented!'
+
+if [ "$#" -gt 0 ]; then
+    search_dirs=("$@")
+else
+    search_dirs=()
+    for d in contracts/*/src crates/*/src; do
+        [ -d "$d" ] && search_dirs+=("$d")
+    done
+fi
+
+if [ "${#search_dirs[@]}" -eq 0 ]; then
+    echo "No source directories found. Nothing to check."
+    exit 0
+fi
+
+violations=0
+files_checked=0
+
+while IFS= read -r file; do
+    files_checked=$((files_checked + 1))
+
+    # Production code is everything above the first #[cfg(test)]. A file without
+    # one is production code throughout.
+    cutoff=$(grep -n '#\[cfg(test)\]' "$file" | head -1 | cut -d: -f1 || true)
+    if [ -n "$cutoff" ]; then
+        end=$((cutoff - 1))
+    else
+        end=$(wc -l < "$file")
+    fi
+    [ "$end" -lt 1 ] && continue
+
+    # Strip line comments and string literals before matching, so prose in a doc
+    # comment and a message inside .expect("...") do not register as calls.
+    hits=$(
+        head -n "$end" "$file" \
+            | sed -e 's://.*::' -e 's:"[^"]*":"":g' \
+            | grep -nE "$BANNED_RE" \
+            || true
+    )
+
+    if [ -n "$hits" ]; then
+        while IFS= read -r hit; do
+            lineno=${hit%%:*}
+            printf '%s:%s: %s\n' "$file" "$lineno" \
+                "$(sed -n "${lineno}p" "$file" | sed 's/^[[:space:]]*//')"
+            violations=$((violations + 1))
+        done <<< "$hits"
+    fi
+done < <(find "${search_dirs[@]}" -name '*.rs' -type f | sort)
+
+if [ "$violations" -gt 0 ]; then
+    echo
+    echo "Found $violations panicking API call(s) in production code."
+    echo
+    echo "Banned in production: ${BANNED_DESC[*]}"
+    echo
+    echo "Convert Option to Result with .ok_or(Error::Variant) and propagate with ?."
+    echo "See requirements.md section 5.1, CONTRIBUTING.md code rules, and ADR-015"
+    echo "for the test-code exception."
+    exit 1
+fi
+
+echo "No panicking APIs in production code. Checked $files_checked file(s)."