@toolu/opencode 6.8.0

package/plugins/rust-quality/hooks/concerns/00-preamble.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# Post-tool check: Rust quality rules.
+# Project-agnostic: no-op outside Rust projects or when cargo is missing.
+# Unsafe-block exemptions for FFI crates come from
+# $TOOLU_SETTINGS_DIR/rust-unsafe-exemptions.txt.
+#
+# Inputs (from parent dispatcher post-tools/mod.sh, via `export`):
+#   $tool_name     - name of the tool being invoked
+#   $input         - raw JSON payload on stdin
+#   $PROJECT_ROOT  - repository root
+
+: "${tool_name:=}"
+: "${input:=}"
+: "${PROJECT_ROOT:=$(pwd)}"
+
+# Core lib comes from the toolu dispatcher via TOOLU_LIB_DIR (set by
+# plugins/toolu/hooks/post-tools/mod.sh before registry dispatch). Outside
+# that pipeline there is no relative path to it — fail SOFT: a quality check
+# must never break a tool call by erroring.
+[ -n "${TOOLU_LIB_DIR:-}" ] && [ -f "$TOOLU_LIB_DIR/detect.sh" ] || exit 0
+# shellcheck source=../../../toolu/hooks/lib/detect.sh
+. "$TOOLU_LIB_DIR/detect.sh"
+# Threshold resolver (defaults + project/native overrides). Soft if absent.
+# shellcheck source=../../../toolu/hooks/lib/quality-config.sh
+[ -f "$TOOLU_LIB_DIR/quality-config.sh" ] && . "$TOOLU_LIB_DIR/quality-config.sh"
+# Multi-slot gate writer (entries keyed by file — one hook's failure no longer
+# clobbers another's). Soft if absent: fallbacks below keep the legacy
+# single-slot behavior when the toolu lib predates gate-file.sh.
+# shellcheck source=../../../toolu/hooks/lib/gate-file.sh
+[ -f "$TOOLU_LIB_DIR/gate-file.sh" ] && . "$TOOLU_LIB_DIR/gate-file.sh"
+command -v gate_record_failure >/dev/null 2>&1 || gate_record_failure() {
+  jq -n --arg reason "$4" --arg source "$3" --arg file "$2" --arg violations "$5" \
+    --arg updatedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    '{status: "failing", reason: $reason, source: $source, file: $file,
+      violations: $violations, updatedAt: $updatedAt}' > "$1"
+}
+command -v gate_clear_file >/dev/null 2>&1 || gate_clear_file() {
+  [ -f "$1" ] || return 0
+  local _src _file
+  _src=$(jq -r '.source // ""' "$1" 2>/dev/null || echo "")
+  _file=$(jq -r '.file // ""' "$1" 2>/dev/null || echo "")
+  if [ "$_src" = "$3" ] && [ "$_file" = "$2" ]; then
+    jq -n --arg source "$3" --arg updatedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+      '{status: "passing", source: $source, updatedAt: $updatedAt}' > "$1"
+  fi
+}
+command -v rust_max_file_lines >/dev/null 2>&1 || rust_max_file_lines() { echo "${DEFAULT_RUST_MAX_FILE_LINES:-500}"; }
+command -v rust_max_fn_lines   >/dev/null 2>&1 || rust_max_fn_lines()   { echo "${DEFAULT_RUST_MAX_FN_LINES:-50}"; }
+command -v rust_max_impl_lines >/dev/null 2>&1 || rust_max_impl_lines() { echo "${DEFAULT_RUST_MAX_IMPL_LINES:-200}"; }
+# Boolean flag reader (e.g. noMocks) — falls back to the caller's default when
+# quality-config.sh predates this reader.
+command -v quality_flag >/dev/null 2>&1 || quality_flag() { printf '%s' "$3"; }
+# count_code_lines comes from detect.sh (sourced above) — no fallback needed.
+
+# Load the merged config ONCE so TOOLU_CFG_LOADED sticks for the threshold
+# lookups below — each runs in a $(...) subshell that inherits it and skips
+# re-merging (otherwise every wrapper re-spawns the jq merge).
+command -v toolu_load_config >/dev/null 2>&1 && toolu_load_config 2>/dev/null || true
+
+[ "$(detect_rust)" = "rust" ] || exit 0
+command -v cargo >/dev/null 2>&1 || exit 0
+command -v jq    >/dev/null 2>&1 || exit 0
+
+TOOLU_SETTINGS_DIR=$(toolu_settings_dir)
+EXEMPTIONS_FILE="$TOOLU_SETTINGS_DIR/rust-unsafe-exemptions.txt"
+
+# read_list is sourced from lib/detect.sh.
+
+fp_from_input=""
+if [[ "$tool_name" == "Write" || "$tool_name" == "Edit" || "$tool_name" == "MultiEdit" ]]; then
+  fp_from_input=$(echo "$input" | jq -r '.tool_input.path // .tool_input.file_path // .tool_input.target_file // empty' 2>/dev/null || echo "")
+fi
+FILE_PATH="${CLAUDE_FILE_PATHS:-$fp_from_input}"
+
+# Deleted files and move sources cannot be linted after apply_patch completes,
+# but their path-owned quality failure must not remain active forever.
+EDIT_OPERATION="${TOOLU_EDIT_OPERATION:-$(echo "$input" | jq -r '.tool_input.toolu_edit_operation // ""' 2>/dev/null || echo "")}"
+EDIT_MOVED_TO="${TOOLU_EDIT_MOVED_TO:-$(echo "$input" | jq -r '.tool_input.toolu_edit_moved_to // ""' 2>/dev/null || echo "")}"
+if [[ "$EDIT_OPERATION" == delete || -n "$EDIT_MOVED_TO" ]]; then
+  if [[ -n "$FILE_PATH" && "$FILE_PATH" =~ \.rs$ ]]; then
+    GATE_FILE="$(toolu_project_state_root "$PROJECT_ROOT")/quality-gate-status.json"
+    gate_clear_file "$GATE_FILE" "$FILE_PATH" "rust-quality-hook"
+  fi
+  exit 0
+fi
+
+[[ -z "$FILE_PATH" || ! -f "$FILE_PATH" ]] && exit 0
+[[ ! "$FILE_PATH" =~ \.rs$ ]] && exit 0
+
+MESSAGES=""
+add_error() {
+  MESSAGES="${MESSAGES}${1}"$'\n'
+}

package/plugins/rust-quality/hooks/concerns/10-size-file.sh

@@ -0,0 +1,10 @@
+RUST_MAX_FILE=$(rust_max_file_lines)
+LINE_COUNT=$(count_code_lines "$FILE_PATH")
+if [[ "$LINE_COUNT" -gt "$RUST_MAX_FILE" ]]; then
+  _split_hint="split into submodules"
+  [ -n "$(detect_clippy)" ] && _split_hint="$_split_hint (clippy enforces complexity here)"
+  _approx=""
+  has_unterminated_block "$FILE_PATH" && _approx=" (size approximated — an unterminated /* or a string containing /* may be affecting the count)"
+  add_error "File exceeds ${RUST_MAX_FILE}-line limit: $FILE_PATH ($LINE_COUNT code lines, blanks/comments excluded)${_approx} — $_split_hint"
+fi
+

package/plugins/rust-quality/hooks/concerns/20-tests.sh

@@ -0,0 +1,84 @@
+_has_inline_cfg_test=0
+# Match bare `#[cfg(test)]` and `test` as the FIRST predicate of an all()/any()
+# combinator (`#[cfg(all(test, feature = "x"))]`, `#[cfg(any(test, ...))]`).
+# Deliberately NOT a loose `cfg(.*\btest\b`: that would false-positive on
+# `#[cfg(not(test))]` (the opposite gate) and `#[cfg(feature = "test-utils")]`
+# (test inside a string). A non-leading `test` predicate (`all(feature, test)`)
+# is the rare miss we accept to keep zero false positives.
+#
+# EXEMPTION: a bare `#[cfg(test)]` that wires a BODYLESS `mod <name>;` decl —
+# single-line (`#[cfg(test)] mod tests;`) or rustfmt's attribute-on-its-own-line
+# two-line form (`#[cfg(test)]` then `mod tests;`) — is a pointer to an external
+# module-sibling tests/ dir, not inline test code, and is not flagged. Further
+# OUTER attributes may sit between the two: `#[path = "tests/stats.rs"]` is the
+# only wiring a crate that bans mod.rs has for a module-sibling test file, so
+# the decl is looked for past any attribute run, bounded so it cannot scan the
+# whole file. Inner attributes (`#![...]`) are deliberately not skipped — they
+# cannot precede a declaration, and neither is an attribute split across lines
+# (`#[path =` / `"x.rs"]`) — same line-based limitation as 30-suppression.sh,
+# and it fails closed: the file is reported rather than silently exempted.
+# Only the BARE cfg(test) form earns this: the
+# all()/any() combinator stays blocked unconditionally (even ahead of a bodyless
+# decl), and any body (`mod tests {`, any line form) stays blocked. grep is
+# line-based, so the multi-line pairing needs awk (getline the next lines); no
+# \b — BSD awk has none, use a negated [[:alnum:]_] class (or line end) for the
+# boundary instead.
+if [[ "$FILE_PATH" == */src/* ]] \
+   && awk '
+       /^[[:space:]]*#\[cfg\((all|any)\(test([^[:alnum:]_]|$)/ { found=1; exit }
+       /^[[:space:]]*#\[cfg\(test\)\][[:space:]]*(pub[[:space:]]+)?mod[[:space:]]+[A-Za-z_][A-Za-z0-9_]*[[:space:]]*;[[:space:]]*(\/\/.*)?$/ { next }
+       /^[[:space:]]*#\[cfg\(test\)\][[:space:]]*$/ {
+         nxt=""
+         # 8 attributes plus the decl line itself — each pass reads one line, so
+         # the bound has to leave room for the decl read or a decl behind the
+         # full 8 attributes is reported.
+         for (i = 0; i < 9; i++) {
+           if ((getline nxt) <= 0) { found=1; exit }
+           if (nxt !~ /^[[:space:]]*#\[[^!]/) break
+         }
+         if (nxt ~ /^[[:space:]]*(pub[[:space:]]+)?mod[[:space:]]+[A-Za-z_][A-Za-z0-9_]*[[:space:]]*;[[:space:]]*(\/\/.*)?$/) { next }
+         found=1; exit
+       }
+       /^[[:space:]]*#\[cfg\(test\)\]/ { found=1; exit }
+       END { exit (found ? 0 : 1) }
+     ' "$FILE_PATH" 2>/dev/null; then
+  add_error "Inline #[cfg(test)] in $FILE_PATH — unit tests belong in a module-sibling tests/ dir wired by a bodyless #[cfg(test)] mod tests; decl; crate-root tests/ is for integration tests"
+  _has_inline_cfg_test=1
+fi
+
+# Test placement: a test-bearing .rs file must live under a tests/ dir, kept
+# flat (only fixtures/helpers/common subdirs allowed — common/mod.rs is the
+# cargo idiom for shared test helpers). Skip when the inline-#[cfg(test)] rule
+# already fired: that's the canonical `src/lib.rs` with `#[cfg(test)] mod tests`
+# pattern, where "move the file to tests/" is wrong (it would orphan the pub
+# items) — the cfg(test) message already says to extract the tests.
+_is_rust_test=0
+case "$(basename "$FILE_PATH")" in
+  *_test.rs|*_tests.rs) _is_rust_test=1 ;;
+esac
+# #[bench] and #[wasm_bindgen_test] are deliberately NOT in the alternation:
+# benches belong in benches/ (cargo convention) and wasm-bindgen tests have no
+# single canonical home — "move to tests/" would be a false positive for both.
+# Generalized over `#[<any::path>::test]` rather than a hardcoded runtime list,
+# so test_log::test, trace_test::test, actix_web::test, etc. all trip the rule;
+# `test_case` (the test_case crate's generator) is added explicitly. `#[rstest]`
+# is its own alternation (the macro name is not `test`). `#[cfg(test)]` is NOT
+# matched here — no `test`/`test_case` token follows `#[` — and stays owned by
+# the inline-cfg(test) rule above.
+if [[ "$_is_rust_test" -eq 0 ]] \
+   && grep -qE '^[[:space:]]*#\[([A-Za-z_][A-Za-z0-9_]*::)*(test|test_case)\b|^[[:space:]]*#\[rstest\b' "$FILE_PATH" 2>/dev/null; then
+  _is_rust_test=1
+fi
+if [[ "$_is_rust_test" -eq 1 && "$_has_inline_cfg_test" -eq 0 ]]; then
+  if [[ "$FILE_PATH" != */tests/* ]]; then
+    add_error "Rust test file outside tests/: $FILE_PATH — move to a sibling tests/ directory"
+  else
+    _after_tests="${FILE_PATH##*/tests/}"
+    if [[ "$_after_tests" == */* ]]; then
+      _subdir="${_after_tests%%/*}"
+      if [[ "$_subdir" != "fixtures" && "$_subdir" != "helpers" && "$_subdir" != "common" ]]; then
+        add_error "Rust test nested in tests/ subdirectory: $FILE_PATH — keep tests/ flat (only fixtures/helpers/common subdirs allowed)"
+      fi
+    fi
+  fi
+fi

package/plugins/rust-quality/hooks/concerns/30-suppression.sh

@@ -0,0 +1,26 @@
+
+# Forbidden lint suppression: #[allow(...)] / #![allow(...)] / #[expect(...)]
+# and the #[cfg_attr(..., allow(...))] / cfg_attr(..., expect(...)) back door.
+# Known limitation: grep is line-based, so an attribute split across multiple
+# lines (e.g. `#[cfg_attr(\n  test,\n  allow(...))]`) escapes detection. Rare;
+# multi-line attribute parsing isn't worth a full tokenizer here.
+#
+# EXEMPTION (tests/ only): the file-level INNER header — `#![allow(...)]` and
+# the `#![cfg_attr(...)]` form of it — is not flagged in a test file. The lints
+# a test suppresses there (unwrap_used, expect_used, panic, float_cmp,
+# too_many_lines) are ones test code violates on purpose: a test that must
+# panic to fail is not a defect being hidden, and the toolu-conventions Rust
+# template prescribes exactly this header. Only the INNER form earns it —
+# a per-item `#[allow(...)]` inside a test file silences one real warning on
+# one real item and stays banned, as everywhere else. Same shape as
+# ts-quality's narrower @ts-expect-error exemption for .test/.spec files.
+_rs_suppress_re='^[[:space:]]*#!?\[(allow|expect)\(|^[[:space:]]*#!?\[cfg_attr\([^]]*\b(allow|expect)\b'
+_rs_suppress_hint=""
+if [[ "$FILE_PATH" == */tests/* ]]; then
+  _rs_suppress_re='^[[:space:]]*#\[(allow|expect)\(|^[[:space:]]*#\[cfg_attr\([^]]*\b(allow|expect)\b'
+  _rs_suppress_hint=" In a test file only the file-level #![allow(...)] header is accepted."
+fi
+if grep -qE "$_rs_suppress_re" "$FILE_PATH" 2>/dev/null; then
+  add_error "Forbidden lint suppression (#[allow]/#[expect]/cfg_attr allow) in $FILE_PATH — remove it and fix the underlying warning in code. For unsafe_code, override in Cargo.toml [lints.rust].${_rs_suppress_hint}"
+fi
+

package/plugins/rust-quality/hooks/concerns/40-unsafe.sh

@@ -0,0 +1,39 @@
+# Forbidden unsafe blocks/functions — except for crates listed in the
+# exemptions file (FFI crates, sandboxes, etc).
+exempt=0
+if [ -f "$EXEMPTIONS_FILE" ]; then
+  while IFS= read -r crate; do
+    [ -z "$crate" ] && continue
+    if [[ "$FILE_PATH" == *"$crate"* ]]; then
+      exempt=1
+      break
+    fi
+  done <<< "$(read_list "$EXEMPTIONS_FILE")"
+fi
+if [ "$exempt" -eq 0 ]; then
+  # Strip // line comments and /* */ blocks (incl. multi-line) before matching,
+  # so a commented-out or doc-mentioned `unsafe {` does not false-positive. The
+  # block-comment state machine mirrors count_code_lines in detect.sh. String
+  # literals containing the pattern are not handled — same heuristic limit as the
+  # other comment-stripping passes here. BSD awk (macOS) has no \b, so explicit
+  # boundaries are used instead.
+  if awk '
+    { line=$0
+      if (inblock) {
+        idx=index(line,"*/")
+        if (idx>0) { line=substr(line, idx+2); inblock=0 } else next
+      }
+      while ((s=index(line,"/*"))>0) {
+        rest=substr(line, s+2); e=index(rest,"*/")
+        if (e>0) { line=substr(line,1,s-1) substr(rest, e+2) }
+        else { line=substr(line,1,s-1); inblock=1; break }
+      }
+      sub(/\/\/.*$/, "", line)        # // line comment
+      if (line ~ /(^|[^A-Za-z0-9_])unsafe[ \t]*(\{|fn )/) { found=1; exit }
+    }
+    END { exit(found ? 0 : 1) }
+  ' "$FILE_PATH" 2>/dev/null; then
+    add_error "Forbidden unsafe code in $FILE_PATH — refactor to safe alternative. Add crate to settings/rust-unsafe-exemptions.txt if it legitimately needs unsafe (FFI, sandboxing)."
+  fi
+fi
+

package/plugins/rust-quality/hooks/concerns/50-size-fn.sh

@@ -0,0 +1,38 @@
+RUST_MAX_FN=$(rust_max_fn_lines)
+# Match fn with any leading visibility/qualifier combo: pub, pub(crate)/pub(super),
+# async, const, unsafe, extern "C", and combinations thereof.
+# The fn end is found with a brace-depth counter from the fn's own line, so a
+# method inside an impl/mod is measured to ITS close (not the impl's), and an
+# inner if/match/loop close can't end the range early. Body-less trait decls
+# (`fn f();`) are released on the `;`. Single-line "..." strings and the
+# '{'/'}' char literals are stripped before counting so a lone brace inside
+# them cannot skew the depth. Known limitation: a brace inside a MULTI-LINE
+# string (incl. raw strings) still leaks into the count — an unbalanced one
+# leaves the fn unmeasured (fail-open), never falsely flagged short.
+LONG_RS_FUNCS=$(awk -v max="$RUST_MAX_FN" -v q="'" '
+  !infn && /^[[:space:]]*(pub(\([^)]+\))?[[:space:]]+)?((async|const|unsafe|extern)([[:space:]]+"[^"]*")?[[:space:]]+)*fn / {
+    infn=1; start=NR; name=$0; depth=0; opened=0
+  }
+  infn {
+    line=$0
+    gsub(/\\"/, "", line)            # escaped quotes would derail the span strip
+    gsub(/"[^"]*"/, "", line)        # single-line string contents
+    gsub(q "[{}]" q, "", line)       # brace char literals (lifetimes never contain braces)
+    no=gsub(/\{/, "{", line); nc=gsub(/\}/, "}", line)
+    depth += no - nc
+    if (no > 0) opened=1
+    if (opened && depth <= 0) {
+      len=NR-start
+      if (len > max) printf "%s:%d (%d lines)\n", name, start, len
+      infn=0
+    }
+    if (!opened && $0 ~ /;[[:space:]]*$/) infn=0
+  }
+' "$FILE_PATH" 2>/dev/null)
+# Test files are exempt: a table-driven test is one long fn by nature, and the
+# toolu-conventions Rust test header prescribes `clippy::too_many_lines` for
+# exactly that reason — flagging it here would contradict the template.
+if [[ -n "$LONG_RS_FUNCS" && "$_is_rust_test" -ne 1 ]]; then
+  add_error "Function too long in $FILE_PATH (>${RUST_MAX_FN} lines) — extract helpers."
+fi
+

package/plugins/rust-quality/hooks/concerns/55-size-impl.sh

@@ -0,0 +1,28 @@
+RUST_MAX_IMPL=$(rust_max_impl_lines)
+# Brace-depth counter (same technique + string/char strip as the fn check):
+# a bare `^\}` close-marker would be tripped early by a column-0 `}` from
+# macro-generated or wide-rustfmt code inside the impl, undercounting it.
+LONG_IMPL=$(awk -v max="$RUST_MAX_IMPL" -v q="'" '
+  !inimpl && /^[[:space:]]*(unsafe[[:space:]]+)?impl[[:space:]<]/ {
+    inimpl=1; start=NR; name=$0; depth=0; opened=0
+  }
+  inimpl {
+    line=$0
+    gsub(/\\"/, "", line)
+    gsub(/"[^"]*"/, "", line)
+    gsub(q "[{}]" q, "", line)
+    no=gsub(/\{/, "{", line); nc=gsub(/\}/, "}", line)
+    depth += no - nc
+    if (no > 0) opened=1
+    if (opened && depth <= 0) {
+      len=NR-start
+      if (len > max) printf "%s:%d (%d lines)\n", name, start, len
+      inimpl=0
+    }
+  }
+' "$FILE_PATH" 2>/dev/null)
+# Exempt in test files, for the same reason as the fn-length rule above.
+if [[ -n "$LONG_IMPL" && "$_is_rust_test" -ne 1 ]]; then
+  add_error "Impl block too large in $FILE_PATH (>${RUST_MAX_IMPL} lines) — split into trait impls or modules."
+fi
+

package/plugins/rust-quality/hooks/concerns/60-error-handling.sh

@@ -0,0 +1,149 @@
+# shellcheck shell=bash
+# --- Error-handling rules (zero tolerance) ---
+# src/ is production code, so any panic-on-error pattern here is a prod panic
+# — EXCEPT in a test file. "tests must live in tests/" is true of the crate-root
+# suite but not of a module-sibling one: a crate that bans mod.rs wires its
+# colocated tests as src/<mod>/tests/<name>.rs, which is under src/ and is still
+# test code. `.unwrap()` there is how a test reports a failed assertion, not a
+# production panic. Same `_is_rust_test` gate 90-docs.sh already uses (set in
+# 20-tests.sh: *_test.rs/*_tests.rs filename, or a #[test]/#[rstest]/#[test_case]
+# attribute in the body).
+if [[ "$FILE_PATH" == */src/* && "$_is_rust_test" -ne 1 ]] && command -v ast-grep >/dev/null 2>&1; then
+  # ONE ast-grep process for all six rules. `ast-grep run -p` re-parses the file
+  # per pattern; `scan --inline-rules` parses once and returns every rule's hits
+  # as JSON. The excerpt lines rebuilt from .file/.range/.lines below are
+  # byte-identical to what `run -p` printed. Mirrors ts-quality/78-error-ast.sh.
+  #
+  # severity is `warning` on purpose: `scan` exits non-zero when an ERROR-level
+  # rule matches, which would be indistinguishable from a crashed tool. At
+  # warning level both a clean and a matching run exit 0, so a non-zero exit (or
+  # any stderr) still means the tool genuinely broke.
+  ast_err_file="$(mktemp)"
+  ast_rules=$(cat <<'RS_AST_RULES'
+id: unwrap
+language: rust
+severity: warning
+message: unwrap on Result/Option
+rule:
+  pattern: '$E.unwrap()'
+---
+id: expect
+language: rust
+severity: warning
+message: expect on Result/Option
+rule:
+  pattern: '$E.expect($M)'
+---
+id: panic
+language: rust
+severity: warning
+message: panic!
+rule:
+  pattern: 'panic!($$$)'
+---
+id: todo
+language: rust
+severity: warning
+message: todo!
+rule:
+  pattern: 'todo!($$$)'
+---
+id: unimplemented
+language: rust
+severity: warning
+message: unimplemented!
+rule:
+  pattern: 'unimplemented!($$$)'
+---
+id: unreachable
+language: rust
+severity: warning
+message: unreachable!
+rule:
+  pattern: 'unreachable!($$$)'
+RS_AST_RULES
+)
+
+  ast_grep_failed=0
+  ast_grep_fail_detail=""
+  ast_lines=""
+  ast_json=$(ast-grep scan --inline-rules "$ast_rules" --json "$FILE_PATH" 2>"$ast_err_file")
+  ast_rc=$?
+  # Flatten every hit to "<ruleId>\t<file>:<line>:<source line>", one output line
+  # per matched source line.
+  #
+  # Two distinct failure modes, reported distinctly: ast-grep itself broke, or it
+  # exited 0 and returned something that is not the documented JSON array. Both
+  # mean the rules could not be verified, but collapsing them into one message
+  # sends the reader to the wrong tool.
+  ast_fail_stage=""
+  if [[ "$ast_rc" -ne 0 || -s "$ast_err_file" ]]; then
+    ast_grep_failed=1
+    ast_fail_stage="ast-grep"
+  elif ! ast_lines=$(printf '%s' "$ast_json" | jq -r '
+        .[] | . as $m
+        | ((($m.lines // "") | split("\n")) | to_entries[])
+        | "\($m.ruleId)\t\($m.file):\($m.range.start.line + 1 + .key):\(.value)"
+      ' 2>/dev/null); then
+    ast_grep_failed=1
+    ast_fail_stage="jq"
+    ast_lines=""
+  fi
+  if [[ "$ast_grep_failed" -ne 0 ]]; then
+    # Exit code plus the first stderr line (capped at ~200 chars) so the surfaced
+    # message tells the agent WHAT broke, not just THAT it broke.
+    ast_stderr_first=$(head -n 1 "$ast_err_file" 2>/dev/null | cut -c1-200)
+    if [[ "$ast_fail_stage" == "jq" ]]; then
+      ast_grep_fail_detail="ast-grep exited 0 but its output did not parse as the documented JSON array"
+    else
+      ast_grep_fail_detail="ast-grep exit ${ast_rc}${ast_stderr_first:+: $ast_stderr_first}"
+    fi
+  fi
+
+  # join_hits BLOCK... — concatenate non-empty hit blocks into $JOINED with one
+  # newline between them. Each block comes from a $(...) capture, which strips the
+  # trailing newline, so plain concatenation glued one block's last line onto the
+  # next block's first line. Sets a variable instead of printing to avoid a fork
+  # on a path that runs after every edit.
+  join_hits() {
+    local _part
+    JOINED=""
+    for _part in "$@"; do
+      [ -z "$_part" ] && continue
+      [ -n "$JOINED" ] && JOINED="${JOINED}"$'\n'
+      JOINED="${JOINED}${_part}"
+    done
+  }
+
+  # ast_hits RULE_ID LIMIT — this rule's excerpt lines, capped like before.
+  ast_hits() {
+    local _id="$1" _limit="$2" _row _rest
+    [ -n "$ast_lines" ] || return 0
+    while IFS=$'\t' read -r _row _rest; do
+      [ "$_row" = "$_id" ] && printf '%s\n' "$_rest"
+    done <<< "$ast_lines" | head -n "$_limit"
+  }
+
+  UNWRAP_HITS=$(ast_hits unwrap 5)
+  if [[ -n "$UNWRAP_HITS" ]]; then
+    add_error ".unwrap() in $FILE_PATH — use ? or match on Result/Option"$'\n'"${UNWRAP_HITS}"
+  fi
+  EXPECT_HITS=$(ast_hits expect 5)
+  if [[ -n "$EXPECT_HITS" ]]; then
+    add_error ".expect() in $FILE_PATH — use ? or match on Result/Option"$'\n'"${EXPECT_HITS}"
+  fi
+
+  PANIC_HITS=$(ast_hits panic 3)
+  TODO_HITS=$(ast_hits todo 3)
+  UNIMPL_HITS=$(ast_hits unimplemented 3)
+  UNREACH_HITS=$(ast_hits unreachable 3)
+  if [[ -n "$PANIC_HITS" || -n "$TODO_HITS" || -n "$UNIMPL_HITS" || -n "$UNREACH_HITS" ]]; then
+    join_hits "$PANIC_HITS" "$TODO_HITS" "$UNIMPL_HITS" "$UNREACH_HITS"
+    add_error "panic!/todo!/unimplemented!/unreachable! in $FILE_PATH — return a Result instead"$'\n'"${JOINED}"
+  fi
+
+  rm -f "$ast_err_file"
+  if [[ "$ast_grep_failed" -ne 0 ]]; then
+    add_error "ast-grep failed while scanning $FILE_PATH — ${ast_grep_fail_detail:-unknown error}; error-handling rules could not be verified. Fix the tool/file and re-edit"
+  fi
+fi

package/plugins/rust-quality/hooks/concerns/70-no-mocks.sh

@@ -0,0 +1,139 @@
+# --- No-mocks (zero tolerance): forbid mock frameworks — real data/fixtures only ---
+# Split scope, because mock *definitions* live in src/ while mock *imports* are
+# pulled into test files:
+#   - src/**/*.rs: #[automock], #[cfg_attr(..., automock)], mock! { ... }
+#     (also the mock!(...) and mock![...] delimiter forms — mock! is a macro,
+#     so all three bracket kinds are valid Rust).
+#   - test files (tests/ placement, or *_test.rs / *_tests.rs basenames — the
+#     same path predicate 20-tests.sh uses; its attribute-based detection
+#     (#[test], #[rstest], ...) is not reused here since mock imports are `use`
+#     statements, not attribute-marked items): use mockall::...;, use faux::...;.
+# Same ast-grep-scan pattern as 60-error-handling.sh: ONE process, severity
+# warning (a matching rule and a clean run both exit 0 — only a genuine crash
+# is distinguishable from a clean pass), jq flattens every hit to one excerpt
+# line, add_error on a match or on tool breakage.
+#
+# Opt-out: lang.rust.noMocks (default true) via quality_flag.
+if [[ "$(quality_flag rust noMocks true)" == "true" ]] && command -v ast-grep >/dev/null 2>&1; then
+  _nm_in_src=0
+  [[ "$FILE_PATH" == */src/* ]] && _nm_in_src=1
+
+  _nm_is_test_file=0
+  [[ "$FILE_PATH" == */tests/* ]] && _nm_is_test_file=1
+  case "$(basename "$FILE_PATH")" in
+    *_test.rs|*_tests.rs) _nm_is_test_file=1 ;;
+  esac
+
+  NM_RULES=""
+  if [[ "$_nm_in_src" -eq 1 ]]; then
+    NM_RULES=$(cat <<'RS_NOMOCK_SRC'
+id: automock-attr
+language: rust
+severity: warning
+message: '#[automock] mock definition'
+rule:
+  pattern: '#[automock]'
+---
+id: automock-cfg-attr
+language: rust
+severity: warning
+message: cfg_attr(..., automock) mock definition
+rule:
+  pattern: '#[cfg_attr($$$, automock)]'
+---
+id: mock-macro
+language: rust
+severity: warning
+message: 'mock! { ... } mock definition'
+rule:
+  any:
+    - pattern: 'mock! { $$$ }'
+    - pattern: 'mock!($$$)'
+    - pattern: 'mock![$$$]'
+RS_NOMOCK_SRC
+)
+  fi
+  if [[ "$_nm_is_test_file" -eq 1 ]]; then
+    NM_TEST_RULES=$(cat <<'RS_NOMOCK_TEST'
+id: mockall-import
+language: rust
+severity: warning
+message: 'use mockall::...; mock import'
+rule:
+  kind: use_declaration
+  regex: 'mockall::'
+---
+id: faux-import
+language: rust
+severity: warning
+message: 'use faux::...; mock import'
+rule:
+  kind: use_declaration
+  regex: 'faux::'
+RS_NOMOCK_TEST
+)
+    if [[ -n "$NM_RULES" ]]; then
+      NM_RULES="${NM_RULES}"$'\n---\n'"${NM_TEST_RULES}"
+    else
+      NM_RULES="$NM_TEST_RULES"
+    fi
+  fi
+
+  if [[ -n "$NM_RULES" ]]; then
+    nm_err_file="$(mktemp)"
+    nm_grep_failed=0
+    nm_fail_detail=""
+    nm_lines=""
+    nm_json=$(ast-grep scan --inline-rules "$NM_RULES" --json "$FILE_PATH" 2>"$nm_err_file")
+    nm_rc=$?
+    # Two distinct failure modes, reported distinctly: ast-grep itself broke, or
+    # it exited 0 and returned something that is not the documented JSON array.
+    if [[ "$nm_rc" -ne 0 || -s "$nm_err_file" ]]; then
+      nm_grep_failed=1
+      nm_stderr_first=$(head -n 1 "$nm_err_file" 2>/dev/null | cut -c1-200)
+      nm_fail_detail="ast-grep exit ${nm_rc}${nm_stderr_first:+: $nm_stderr_first}"
+    elif [[ -z "$(printf '%s' "$nm_json" | tr -d '[:space:]')" ]]; then
+      # ast-grep exited 0 with genuinely empty stdout — jq also exits 0 on
+      # empty input with empty output, so left unchecked this would be
+      # indistinguishable from a clean "[]" scan and silently swallow a real
+      # breakage as "no hits". A well-behaved scan always emits at least "[]".
+      nm_grep_failed=1
+      nm_fail_detail="ast-grep exited 0 with empty output (expected at least the JSON array \"[]\")"
+    elif ! nm_lines=$(printf '%s' "$nm_json" | jq -r '
+          .[] | . as $m
+          | ((($m.lines // "") | split("\n")) | to_entries[])
+          | "\($m.ruleId)\t\($m.file):\($m.range.start.line + 1 + .key):\(.value)"
+        ' 2>/dev/null); then
+      nm_grep_failed=1
+      nm_fail_detail="ast-grep exited 0 but its output did not parse as the documented JSON array"
+      nm_lines=""
+    fi
+
+    # nm_hits RULE_ID LIMIT — this rule's excerpt lines, capped.
+    nm_hits() {
+      local _id="$1" _limit="$2" _row _rest
+      [ -n "$nm_lines" ] || return 0
+      while IFS=$'\t' read -r _row _rest; do
+        [ "$_row" = "$_id" ] && printf '%s\n' "$_rest"
+      done <<< "$nm_lines" | head -n "$_limit"
+    }
+
+    AUTOMOCK_HITS=$(nm_hits automock-attr 5; nm_hits automock-cfg-attr 5)
+    if [[ -n "$AUTOMOCK_HITS" ]]; then
+      add_error "no-mocks: #[automock] mock definition in $FILE_PATH — write against real data/fixtures instead"$'\n'"${AUTOMOCK_HITS}"
+    fi
+    MOCK_MACRO_HITS=$(nm_hits mock-macro 5)
+    if [[ -n "$MOCK_MACRO_HITS" ]]; then
+      add_error "no-mocks: mock! { ... } mock definition in $FILE_PATH — write against real data/fixtures instead"$'\n'"${MOCK_MACRO_HITS}"
+    fi
+    MOCK_IMPORT_HITS=$(nm_hits mockall-import 5; nm_hits faux-import 5)
+    if [[ -n "$MOCK_IMPORT_HITS" ]]; then
+      add_error "no-mocks: mockall/faux import in $FILE_PATH — write against real data/fixtures instead"$'\n'"${MOCK_IMPORT_HITS}"
+    fi
+
+    rm -f "$nm_err_file"
+    if [[ "$nm_grep_failed" -ne 0 ]]; then
+      add_error "ast-grep failed while scanning $FILE_PATH — ${nm_fail_detail:-unknown error}; no-mocks rules could not be verified. Fix the tool/file and re-edit"
+    fi
+  fi
+fi

package/plugins/rust-quality/hooks/concerns/90-docs.sh

@@ -0,0 +1,32 @@
+# --- Docs (soft advisory, never blocks) ---
+# A public API item in src/ should carry a concise /// doc comment. Advisory
+# only — collected separately from MESSAGES so it never sets the failing gate.
+DOC_ADVISORY=""
+if [[ "$FILE_PATH" == */src/* && ! "$_is_rust_test" -eq 1 ]]; then
+  _undoc=$(awk '
+    /^[[:space:]]*$/   { next }   # blanks do not reset the doc context
+    /^[[:space:]]*#\[/ { next }   # attributes sit between doc and item
+    {
+      if ($0 ~ /^[[:space:]]*pub(\([^)]+\))?[[:space:]]+(fn|struct|enum|trait|const|static|type|mod)[[:space:]]/) {
+        if (prev !~ /^[[:space:]]*(\/\/\/|\/\/!)/) printf "%d: %s\n", NR, $0
+      }
+      prev=$0
+    }
+  ' "$FILE_PATH" 2>/dev/null | head -3)
+  if [[ -n "$_undoc" ]]; then
+    DOC_ADVISORY="Public items missing a /// doc comment in $FILE_PATH — add a concise one-line doc:"$'\n'"${_undoc}"
+  fi
+  # Concise cap: flag doc-comment runs that have grown long.
+  _verbose_doc=$(awk '
+    /^[[:space:]]*\/\/[\/!]/ { if (run==0) start=NR; run++; next }
+    { if (run>12) printf "%d: doc block is %d lines — trim to the essentials\n", start, run; run=0 }
+    END { if (run>12) printf "%d: doc block is %d lines — trim to the essentials\n", start, run }
+  ' "$FILE_PATH" 2>/dev/null | head -2)
+  if [[ -n "$_verbose_doc" ]]; then
+    # Separator appended on its own line: ANSI-C quoting is NOT honored inside a
+    # ${var:+word} expansion, so it cannot be inlined there.
+    [[ -n "$DOC_ADVISORY" ]] && DOC_ADVISORY="${DOC_ADVISORY}"$'\n'
+    DOC_ADVISORY="${DOC_ADVISORY}Verbose doc comment in $FILE_PATH — docs must be present but concise:"$'\n'"${_verbose_doc}"
+  fi
+fi
+