gradle-report: name UP-TO-DATE as the cause of a stale report

Found by running it: detekt exited 0 while the report predated the run,
because Gradle skipped the task. 'STALE' alone leaves the reader to work out
why nothing changed, so it now says which task was skipped and how to force
it, with --allow-stale to accept an older report deliberately. Same shape as
gradle-test, which learned this first.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018AwnALZL6bD4VBtATDVv3B

3 files changed, 38 insertions, 5 deletions

diff --git a/README.md b/README.md
index a41b312..eff764a 100644
--- a/README.md
+++ b/README.md
@@ -103,7 +103,7 @@ code that no longer exists — which is exactly what happened three times in one
 session, the giveaway being line numbers that never moved after a refactor.
 
 ```
-gradle-report /workspace/listen detekt
+gradle-report /workspace/listen detekt -- --rerun-tasks
 ```
 
 Prints `CONFIG INVALID` and names the offending property when the config is
diff --git a/bin/gradle-report b/bin/gradle-report
index c59945a..bbee2b7 100755
--- a/bin/gradle-report
+++ b/bin/gradle-report
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# gradle-report <project-dir> <detekt|lint> -- [gradle args]
+# gradle-report <project-dir> <detekt|lint> [--allow-stale] [-- <gradle args>]
 #
 # Runs a static-analysis task and reports from its XML report, refusing to speak if the report
 # is older than the run.
@@ -18,6 +18,8 @@ die() { echo "gradle-report: $1" >&2; exit 2; }
 PROJECT_DIR=$(cd "$1" 2>/dev/null && pwd) || die "no such project directory: $1"
 KIND="$2"
 shift 2
+ALLOW_STALE=0
+if [ "${1:-}" = "--allow-stale" ]; then ALLOW_STALE=1; shift; fi
 [ "${1:-}" = "--" ] && shift
 EXTRA=("$@")
 
@@ -62,8 +64,15 @@ if [ ! -f "$REPORT" ]; then
     exit $STATUS
 fi
 
-if [ "$REPORT" -ot "$MARKER" ]; then
+if [ "$REPORT" -ot "$MARKER" ] && [ $ALLOW_STALE -eq 0 ]; then
     echo "report  : STALE — $REPORT predates this run"
+    if grep -qE "Task :app:(detekt|lintDebug) UP-TO-DATE" "$LOG"; then
+        echo "hint    : Gradle treated $TASK as UP-TO-DATE, so nothing was re-analysed and the"
+        echo "          report on disk describes an earlier state of the code."
+        echo "          Re-run with: -- --rerun-tasks   (or --allow-stale to accept it)"
+    else
+        echo "hint    : the task ran but produced no new report. Re-run with: -- --rerun-tasks"
+    fi
     echo "result  : FAIL — refusing to report numbers that describe older code"
     rm -f "$LOG"
     exit 1
@@ -96,7 +105,11 @@ for r in rows:
 PY
 )
 
-echo "report  : fresh"
+if [ "$REPORT" -ot "$MARKER" ]; then
+    echo "report  : STALE (accepted via --allow-stale)"
+else
+    echo "report  : fresh"
+fi
 echo "$FINDINGS" | head -1 | sed 's/^COUNT /findings: /'
 echo "$FINDINGS" | tail -n +2
 
diff --git a/test/run-tests.sh b/test/run-tests.sh
index 6e8ae43..a88e024 100755
--- a/test/run-tests.sh
+++ b/test/run-tests.sh
@@ -195,7 +195,27 @@ else
   bad "stale report detection" "rc=$rc out=$out"
 fi
 
-# 15. A missing project directory is fatal, never a silent fallback to cwd.
+# 15. UP-TO-DATE is the common way a report goes stale, so say so rather than leaving the
+#     reader to work out why nothing changed.
+d="$tmproot/report-uptodate"
+make_project "$d" 0 'echo "> Task :app:detekt UP-TO-DATE"'
+mkdir -p "$d/app/build/reports/detekt"
+printf '<?xml version="1.0"?><checkstyle></checkstyle>' > "$d/app/build/reports/detekt/detekt.xml"
+touch -d '2020-01-01' "$d/app/build/reports/detekt/detekt.xml"
+out=$("$BIN/gradle-report" "$d" detekt 2>&1); rc=$?
+if [ $rc -ne 0 ] && printf '%s' "$out" | grep -qi "UP-TO-DATE"; then
+  ok "explains an UP-TO-DATE task rather than just saying stale"
+else
+  bad "up-to-date hint" "rc=$rc out=$out"
+fi
+out=$("$BIN/gradle-report" "$d" detekt --allow-stale 2>&1); rc=$?
+if [ $rc -eq 0 ] && printf '%s' "$out" | grep -qi "allow-stale"; then
+  ok "--allow-stale opts in to an older report"
+else
+  bad "allow-stale" "rc=$rc out=$out"
+fi
+
+# 16. A missing project directory is fatal, never a silent fallback to cwd.
 out=$("$BIN/gradle-report" "$tmproot/nope" detekt 2>&1); rc=$?
 if [ $rc -eq 2 ]; then ok "missing project dir is fatal"; else bad "missing dir" "rc=$rc"; fi