@spardutti/claude-skills 2.36.0 → 2.37.0

package/hooks/gauntlet.sh

@@ -28,6 +28,7 @@
 #   GAUNTLET_CODE_EXT="ts|tsx|py"  override which extensions count as code
 #   GAUNTLET_DEBUG=1               print the outcome to stderr on every run
 #   GAUNTLET_REQUIRE_TESTS=1       block when a runner matched 0 test files
+#   GAUNTLET_SLOW=30               warn the user when a run takes this many seconds
 #
 # Setting either command switches the whole repo to explicit mode — auto-detection
 # is off, and only what you set runs.
@@ -64,8 +65,9 @@ WHY="$MARKER.why"
 
 # Records why this run ended, so "green" and "never ran" stop looking identical.
 quit() {
-  printf '%s\n' "$1" > "$WHY" 2>/dev/null
+  printf '%s (%ss)\n' "$1" "$SECONDS" > "$WHY" 2>/dev/null
   if [ -n "${GAUNTLET_DEBUG:-}" ]; then printf 'gauntlet: %s\n' "$1" >&2; fi
+  [ "$SECONDS" -ge "${GAUNTLET_SLOW:-30}" ] && printf '{"systemMessage":"gauntlet took %ss, target %ss: %s"}\n' "$SECONDS" "${GAUNTLET_SLOW:-30}" "$1"
   exit 0
 }
 
@@ -119,13 +121,8 @@ SKIP_NOTE=""
 
 add_gate() {  # kind (typecheck|tests), file regex, command
   LINE=$(printf '%s\t%s\t%s' "$1" "$2" "$3")
-  if [ "$1" = "typecheck" ]; then
-    TC_GATES="$TC_GATES$LINE
-"
-  else
-    TEST_GATES="$TEST_GATES$LINE
-"
-  fi
+  if [ "$1" = "typecheck" ]; then TC_GATES="$TC_GATES$LINE"$'\n'
+  else TEST_GATES="$TEST_GATES$LINE"$'\n'; fi
 }
 
 JS_EXT='(ts|tsx|js|jsx|mjs|cjs)'
@@ -318,7 +315,7 @@ $FILES
 --- $FAILED output (last 60 lines) ---
 $TAIL"
 
-printf '%s\n' "red: the $FAILED gate failed" > "$WHY" 2>/dev/null
+printf '%s\n' "red: the $FAILED gate failed (${SECONDS}s)" > "$WHY" 2>/dev/null
 
 # Exit 2 is the only path where a red is visible to the user: its stderr is shown
 # to them as the reason the turn is continuing. Exit 0 with {"decision":"continue"}

package/hooks/ship-gate-projects.sh

@@ -36,12 +36,16 @@ owner_of() {
 # Blaming an unreachable database for that sent one agent chasing Docker for 20 minutes.
 mutmut_unchecked() {  # mutmut_unchecked <label> <base> <count> <run log>
   echo "  $1 mutmut — UNPROVEN: $3 mutant(s) were never run."
-  stop='Failed to run clean test|failed to collect stats|Failed to collect list of tests|Stopping early'
+  # "Failed to run pytest with args" is one line carrying every selected test id — 20KB of
+  # them on one repo — so the line is cut. Unlisted, the gate blamed a database instead.
+  stop='Failed to run clean test|failed to collect stats|Failed to collect list of tests|Stopping early|Failed to run pytest with args|BadTestExecutionCommandsException'
   if grep -aqsE "$stop" "$4"; then
     echo "      mutmut stopped before testing a single mutant:"
-    grep -aE "^(FAILED|ERROR) |^[A-Za-z]*Error: |$stop" "$4" | tail -8 | sed 's/^/        /'
+    grep -aE "^(FAILED|ERROR) |^[A-Za-z]*Error: |$stop" "$4" | tail -8 | cut -c1-200 | sed 's/^/        /'
     echo "      It runs the whole suite, then these tests again in one process, so a"
     echo "      test that passes alone can fail here on state an earlier test left."
+    echo "      mutmut hides pytest's own error: set debug = true under [tool.mutmut]"
+    echo "      and run it again to read it."
     return
   fi
   echo "      They are recorded \"not checked\", so the suite proved nothing"
@@ -79,12 +83,30 @@ receipt_key() {
 
 # A scoped --baseline replaces only the changed modules' names. Rebuilding the whole
 # file re-mutated an entire API to accept eleven of them.
-baseline_write() {  # baseline_write <baseline file> <survivors file> <scope regex, or empty>
+baseline_write() {  # baseline_write <baseline file> <survivors file> <scope regex, or empty> [modules]
   if [ -z "$3" ]; then cp "$2" "$1"; return; fi
-  grep -vE "^($3)\.x" "$1" | cat - "$2" | sort -u > "$1.new"
+  { grep -vE "^($3)\.x" "$1"; cat "$2"; baseline_marked "$1" && printf '# module %s\n' $4; } | sort -u > "$1.new"
   mv "$1.new" "$1"
 }
 
+# A baseline names each module it has run as "# module <name>", so a first run tests only the diff.
+# One with no such line predates them and came from a whole-repo run, so it covers every module.
+baseline_marked() { [ ! -f "$1" ] || grep -q '^# module ' "$1"; }
+baseline_uncovered() {  # baseline_uncovered <baseline> <modules>: the ones it has never run
+  for m in $2; do baseline_marked "$1" && ! grep -qsx "# module $m" "$1" && echo "$m"; done
+}
+
+# A module's survivors on its first run predate this gate, so they are recorded, not charged.
+baseline_first() {  # baseline_first <baseline> <survivors file> <modules> <label>; false when none are new
+  new=$(baseline_uncovered "$1" "$3"); [ -n "$new" ] || return 1
+  re=$(printf '%s\n' $new | sed 's/\./\\./g' | paste -sd'|' -)
+  n=$(grep -cE "^($re)\.x" "$2")
+  { cat "$1" 2>/dev/null; grep -E "^($re)\.x" "$2"; printf '# module %s\n' $new; } | sort -u > "$1.new"
+  mv "$1.new" "$1"
+  echo "  $4 mutmut — first run for $(echo $new): $n existing survivor(s) recorded in $1."
+  echo "      Commit it. From here only NEW survivors in these modules fail."
+}
+
 family_of() {  # js, py, or any when no manifest says
   o=$(owner_of "$1")
   if [ -f "$o/package.json" ]; then echo js

package/hooks/ship-gate-structure.sh

@@ -96,7 +96,7 @@ structure_check() {
 
 # Called when nothing else in the diff is gated, so the gate would otherwise pass it.
 structure_fail() {
-  echo "ship-gate: FAIL — deal with the findings above, then run this again."
+  echo "ship-gate: FAIL in ${SECONDS}s — deal with the findings above, then run this again."
   echo "           To ship anyway: bash .claude/hooks/ship-gate.sh --force"
   rm -f "$RECEIPT"
   exit 1

package/hooks/ship-gate.sh

@@ -207,7 +207,7 @@ elif [ -n "$OVER" ]; then
 else
   echo "FILE LENGTH — ok, largest is $LARGEST lines"
 fi
-
+[ "$STATUS" = 1 ] && { echo; echo "MUTATION — skipped: the fix changes the files, so it would run again"; structure_fail; }
 # ---------------------------------------------------------- which project owns
 # A monorepo holds several projects, each with its own runner and its own
 # mutation tool. Walk up from each changed file to the nearest manifest.
@@ -256,9 +256,9 @@ for owner in $OWNERS; do
 
   base=""; RUN=""; SCOPE_RE=""; GLOBS=""; MODS=""; MLOG="${TMPDIR:-/tmp}/ship-gate-mutmut.$$"
   if [ "$owner" != "." ]; then base="$owner/"; RUN="cd '$owner' && "; fi
-  if [ -n "$GAUNTLET_MUTATE" ]; then
-    CMD="$GAUNTLET_MUTATE"; TOOL="config"
-  elif [ -f "$base"package.json ] && grep -qs '@stryker-mutator/core' "$base"package.json; then
+  PY=$(printf '%s\n' "$OWNED" | grep '\.py$' || true)  # a husky-only package.json must not claim a Python diff
+  if [ -n "$GAUNTLET_MUTATE" ]; then CMD="$GAUNTLET_MUTATE"; TOOL="config"
+  elif [ -z "$PY" ] && grep -qs '@stryker-mutator/core' "$base"package.json; then
     TOOL="stryker"
     # From inside the owning package: npx resolves against ITS node_modules, and
     # stryker.config.json lives there too. A monorepo root usually has neither.
@@ -272,7 +272,7 @@ for owner in $OWNERS; do
     # the run to the changed hunks, so incremental buys nothing here and costs
     # a cache that goes stale exactly the way mutmut's did.
     CMD="${RUN}npx --no-install stryker run --mutate '${FLAGS#,}'"; stryker_page_tests "$base" "$label"
-  elif [ -f "$base"package.json ]; then
+  elif [ -z "$PY" ] && [ -f "$base"package.json ]; then
     MISSING="$MISSING  $label needs Stryker:
       npm --prefix ${owner} i -D @stryker-mutator/core @stryker-mutator/vitest-runner
       then ${base}stryker.config.json:
@@ -281,15 +281,14 @@ for owner in $OWNERS; do
     continue
   elif [ -n "$(py_mutmut "$base")" ]; then
     TOOL="mutmut"
-    # 3.x has no per-line scoping, only fnmatch globs over mutant NAMES, so once a
-    # baseline exists every run, --baseline included, is scoped to the changed modules.
+    # 3.x scopes only by fnmatch globs over mutant NAMES, so every run is scoped to the changed modules.
     #
     # `mutmut run` prints 🙁 for a survivor and exits 0 either way — parsing it
     # reports clean with survivors sitting there, which is a false green and
     # worse than reporting nothing. `mutmut results` is the readable source:
     # it prints "<mutant name>: survived" per survivor.
     M="$(py_mutmut "$base")"
-    [ -f "$base.mutmut-baseline" ] && MODS=$(printf '%s\n' "$OWNED" \
+    MODS=$(printf '%s\n' "$OWNED" \
       | sed -n "s#^$base\(.*\)\.py\$#\1#p" | tr / . | sed 's#^src\.##' | sort -u)
     [ -n "$MODS" ] && GLOBS=$(printf " '%s.x*'" $MODS) \
       && SCOPE_RE=$(printf '%s\n' "$MODS" | sed 's/\./\\./g' | paste -sd'|' -)
@@ -322,7 +321,7 @@ for owner in $OWNERS; do
     continue
   fi
   [ "$TOOL" = mutmut ] && [ "$MODE" = baseline ] && [ -f "$PKEY.out" ] && CMD="cp '$PKEY.log' '$MLOG' 2>/dev/null; cat '$PKEY.out'"
-  OUT=$(eval "$CMD" 2>&1); RC=$?
+  T0=$SECONDS; OUT=$(export FILES="$(printf '%s' "$OWNED" | tr '\n' ' ')" MUTATE_FLAGS="--mutate ${FLAGS#,}"; eval "$CMD" 2>&1); RC=$?; T=$((SECONDS - T0))
   [ "$TOOL" = mutmut ] && [ $RC -eq 0 ] && { printf '%s\n' "$OUT" > "$PKEY.out"; cp "$MLOG" "$PKEY.log" 2>/dev/null; }
   [ -n "$SCOPE_RE" ] && [ $RC -eq 0 ] && OUT=$(printf '%s\n' "$OUT" | grep -E "^[[:space:]]*($SCOPE_RE)\.x")
   # Match a finding, never a summary row. Stryker prints a `# survived` COLUMN
@@ -397,8 +396,9 @@ for owner in $OWNERS; do
       continue
     fi
 
+    [ "$MODE" != baseline ] && baseline_first "$BL" "$NOWF" "$MODS" "$label" && [ "$STATUS" = 0 ] && STATUS=2
     if [ "$MODE" = baseline ]; then
-      baseline_write "$BL" "$NOWF" "$SCOPE_RE"
+      baseline_write "$BL" "$NOWF" "$SCOPE_RE" "$MODS"
       NOTE="  $label mutmut — baseline set: $(wc -l < "$BL") survivor(s) accepted. Commit $BL."
       SURVIVED=""
     elif [ -f "$BL" ]; then
@@ -418,7 +418,7 @@ for owner in $OWNERS; do
   fi
 
   if [ -n "$SURVIVED" ]; then
-    echo "  $label $TOOL — these lines can break and no test notices:"
+    echo "  $label $TOOL (${T}s) — these lines can break and no test notices:"
     survivor_list "$SURVIVED" "$TOOL"
     if [ "$FOUND" -gt 20 ]; then
       echo "      ... $((FOUND - 20)) more not shown. Every file with findings:"
@@ -432,13 +432,13 @@ for owner in $OWNERS; do
     [ "$FIXED" -gt 0 ] && echo "      ($FIXED baselined survivor(s) now killed — --baseline banks them)"
     STATUS=1
   elif [ $RC -ne 0 ]; then
-    echo "  $label $TOOL — the run failed:"
+    echo "  $label $TOOL (${T}s) — the run failed:"
     printf '%s\n' "$OUT" | tail -12 | sed 's/^/      /'
     [ "$STATUS" = 0 ] && STATUS=2
   elif [ -n "$NOTE" ]; then
     printf '%s\n' "$NOTE"
   else
-    echo "  $label $TOOL — ok, nothing survived and nothing was uncovered"
+    echo "  $label $TOOL (${T}s) — ok, nothing survived and nothing was uncovered"
     [ -n "$PKEY" ] && touch "$PKEY"
     [ "$FIXED" -gt 0 ] && echo "      ($FIXED baselined survivor(s) now killed — --baseline banks them)"
   fi
@@ -459,12 +459,12 @@ fi
 # a choice that can be argued for, but it cannot be passed off as this one.
 echo
 case $STATUS in
-  0) echo "ship-gate: PASS"
+  0) echo "ship-gate: PASS in ${SECONDS}s"
      printf 'PASS %s\n' "$(date -u +%FT%TZ)" > "$RECEIPT" ;;
-  1) echo "ship-gate: FAIL — deal with the findings above, then run this again."
+  1) echo "ship-gate: FAIL in ${SECONDS}s — deal with the findings above, then run this again."
      echo "           To ship anyway: bash .claude/hooks/ship-gate.sh --force"
      rm -f "$RECEIPT" ;;
-  2) echo "ship-gate: UNPROVEN — nothing is wrong, but nothing was proven either"
+  2) echo "ship-gate: UNPROVEN in ${SECONDS}s — nothing is wrong, but nothing was proven either"
      printf 'UNPROVEN %s\n' "$(date -u +%FT%TZ)" > "$RECEIPT" ;;
 esac
 exit $STATUS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.36.0",
+  "version": "2.37.0",
   "description": "Guardrails for Claude Code — best-practice skills, planning commands, and delivery gates.",
   "type": "module",
   "repository": {