@spardutti/claude-skills 2.45.0 → 2.46.0

package/hooks/ship-gate-files.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# Sourced by ship-gate.sh: which changed files a Stryker run can skip, and what its output says.
+
+TEST_RE='(\.|_)(test|spec)\.[^.]+$|(^|/)tests?/'
+
+stryker_owner() {  # stryker_owner <owner> <owned files>
+  b=""; [ "$1" != "." ] && b="$1/"
+  [ -z "$GAUNTLET_MUTATE" ] && ! grep -q '\.py$' <<< "$2" \
+    && grep -qs '@stryker-mutator/core' "${b}package.json"
+}
+
+changed_tests() {  # changed_tests <family>
+  printf '%s\n' "$CHANGED" | grep -E "$TEST_RE" | while IFS= read -r t; do
+    [ -n "$t" ] && [ "$(family_of "$t")" = "$1" ] && printf '%s\n' "$t"
+  done
+}
+
+# Everything a file's verdict rests on besides the file itself and the tests.
+# Tests are left out: adding to them can only kill more, so only a lost line counts.
+files_context() {  # files_context <owner> <owned files>
+  fam=$(family_of "$1/.")
+  { printf '%s\n' "$PROJECT_DIR" "$1" "$(git rev-parse "$BASE" 2>/dev/null)"
+    cat "$HERE/ship-gate.sh" "$HERE/ship-gate-projects.sh" "$HERE/ship-gate-files.sh"
+    printf '%s\n' "$CHANGED" | grep -vE '\.(md|mdx|txt|rst|adoc)$' | grep -vE "$TEST_RE" \
+      | grep -vxF -f <(printf '%s\n' "$2") | while IFS= read -r f; do
+      [ -n "$f" ] || continue
+      case "$(family_of "$f")" in "$fam"|any) printf '%s\n' "$f"; [ -f "$f" ] && cat "$f" ;; esac
+    done; } | git hash-object --stdin
+}
+
+file_receipt() {  # file_receipt <context> <file>
+  printf '/tmp/claude-shipgate-file-%s\n' "$({ printf '%s\n' "$1" "$2"; cat "$2"; } | git hash-object --stdin)"
+}
+
+test_then() {  # test_then <snapshot> <test>: its content when the snapshot was taken
+  if grep -qxF "$2" "$1/manifest"; then cat "$1/files/$2" 2>/dev/null
+  else git show "$BASE:$2" 2>/dev/null; fi
+}
+
+# Never `| grep -q` under pipefail: diff exits 1 on any difference, and an early
+# grep exit fails the writer, so a match reads as none.
+tests_lost_lines() {  # tests_lost_lines <snapshot> <family>
+  [ -f "$1/manifest" ] || return 0
+  while IFS= read -r t; do
+    [ -n "$t" ] || continue
+    case "$(diff <(test_then "$1" "$t") <(cat "$t" 2>/dev/null))" in *$'\n<'*) return 0 ;; esac
+  done <<< "$({ cat "$1/manifest"; changed_tests "$2"; } | sort -u)"
+  return 1
+}
+
+# Sets OWNED to the files that still need mutating.
+files_split() {  # files_split <context> <owner> <label>
+  fam=$(family_of "$2/."); kept=""; rest=""
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    r=$(file_receipt "$1" "$f")
+    if [ -f "$r" ] && ! tests_lost_lines "$(cat "$r")" "$fam"; then kept="$kept ${f#"$2"/}"
+    else rest="$rest$f"$'\n'; fi
+  done <<< "$OWNED"
+  OWNED=${rest%$'\n'}
+  [ -n "$kept" ] || return 0
+  echo "  $3 stryker — ok, not re-run: passed and unchanged since:$kept"
+  echo "      A change in a file they call is not re-checked."
+  b=""; [ "$2" != "." ] && b="$2/"
+  [ -z "$OWNED" ] && stryker_page_tests "$b" "$3"
+  return 0
+}
+
+# A finding with no location cannot be pinned on one file, so it keeps none.
+files_record() {  # files_record <context> <owner> <findings>
+  [ -n "$(printf '%s\n' "$3" | grep . | grep -vE ':[0-9]+:[0-9]+$')" ] && return 0
+  fam=$(family_of "$2/.")
+  snap="/tmp/claude-shipgate-tests-$({ printf '%s\n' "$1"; changed_tests "$fam" \
+    | while IFS= read -r t; do printf '%s\n' "$t"; cat "$t" 2>/dev/null; done; } | git hash-object --stdin)"
+  mkdir -p "$snap/files"; changed_tests "$fam" > "$snap/manifest"
+  while IFS= read -r t; do
+    [ -f "$t" ] && mkdir -p "$snap/files/$(dirname "$t")" && cp "$t" "$snap/files/$t"
+  done < "$snap/manifest"
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    grep -qF "  ${f#"$2"/}:" <<< "$3" && continue
+    printf '%s\n' "$snap" > "$(file_receipt "$1" "$f")"
+  done <<< "$OWNED"
+}
+
+# Match a finding, never a summary row. Stryker prints a `# survived` COLUMN
+# HEADER every run and repeats the word in its table, so a bare grep reports
+# survivors on a clean run — worse than not running at all. Stryker marks each
+# real finding `[Survived]`; table and border lines are excluded outright.
+# NoCoverage is printed exactly like Survived and means something worse: not
+# "a test missed this mutation" but "no test executes this line at all". The
+# gate matched only [Survived], so a diff whose files have no tests came back
+# PASS — 306 uncovered mutants reported as proven on one commit. It is judged
+# only for files that went in WITH a range: a glob-shaped path is mutated
+# whole, so its untouched lines would report uncovered forever, and a finding
+# nobody can close is what teaches people to --force.
+#
+# The status line carries no file name; the line under it does, as
+# file:line:column. They are paired here rather than grepped separately.
+stryker_findings() {  # stryker_findings <output> <globbed paths, comma-wrapped>
+  printf '%s\n' "$1" | awk -v globbed="$2" '
+    /^\[Survived\]/   { pend = $0; kind = "s"; next }
+    /^\[NoCoverage\]/ { pend = $0; kind = "n"; next }
+    pend != "" {
+      file = $0; sub(/:[0-9]+:[0-9]+$/, "", file)
+      if (kind == "s" || index(globbed, "," file ",") == 0) print pend "  " $0
+      pend = ""
+    }
+    # A survivor with no location under it is still a survivor, never dropped.
+    END { if (pend != "" && kind == "s") print pend }
+  '
+}

package/hooks/ship-gate-projects.sh

@@ -25,6 +25,18 @@ py_mutmut() {
   command -v mutmut >/dev/null 2>&1 && printf 'mutmut\n'
 }
 
+# Node that lives only in Docker leaves no Stryker on the host. An executable
+# .stryker-run runs it there instead, taking the arguments stryker would.
+stryker_bin() { if [ -x "$1.stryker-run" ]; then echo ./.stryker-run; else echo npx --no-install stryker; fi; }
+stryker_elsewhere() {  # stryker_elsewhere <tool> <base>: after a failed run, say where Stryker could run
+  [ "$1" = stryker ] && [ ! -x "$2.stryker-run" ] || return 0
+  d=$(cd "${2:-.}" && pwd)
+  while [ "$d" != / ]; do [ -d "$d/node_modules/@stryker-mutator/core" ] && return 0; d=$(dirname "$d"); done
+  echo "      Stryker is not installed on this machine. If Node runs only in Docker, add an"
+  echo "      executable $2.stryker-run that runs it there and passes on its arguments:"
+  echo "        docker compose run --rm -T <service> nice -n 19 npx stryker \"\$@\""
+}
+
 owner_of() {
   d=$(dirname "$1")
   while :; do
@@ -127,7 +139,7 @@ project_key() {  # project_key <owner> <tool>
   fam=$(family_of "$1/.")
   { printf '%s\n' "$PROJECT_DIR" "$1" "$2" "$(git rev-parse "$BASE" 2>/dev/null)" \
       "$GAUNTLET_NO_MUTATE" "$GAUNTLET_IGNORE_FILES"
-    cat "$HERE/ship-gate.sh" "$HERE/ship-gate-projects.sh"
+    cat "$HERE/ship-gate.sh" "$HERE/ship-gate-projects.sh" "$HERE/ship-gate-files.sh"
     printf '%s\n' "$CHANGED" | grep -vE '\.(md|mdx|txt|rst|adoc)$' | while IFS= read -r f; do
       [ -n "$f" ] || continue
       case "$(family_of "$f")" in "$fam"|any) printf '%s\n' "$f"; [ -f "$f" ] && cat "$f" ;; esac

package/hooks/ship-gate.sh

@@ -46,7 +46,7 @@
 set -uo pipefail
 
 HERE=$(cd "$(dirname "$0")" && pwd)
-. "$HERE/ship-gate-projects.sh" && . "$HERE/ship-gate-structure.sh" || { echo "ship-gate: cannot read its helpers in $HERE"; exit 1; }
+. "$HERE/ship-gate-projects.sh" && . "$HERE/ship-gate-structure.sh" && . "$HERE/ship-gate-files.sh" || { echo "ship-gate: cannot read its helpers in $HERE"; exit 1; }
 
 MODE=""
 case "${1:-}" in
@@ -122,7 +122,7 @@ if [ "$MODE" = force ]; then
 fi
 gate_report "$RECEIPT_KEY"
 SOURCED=$(printf '%s\n' "$CHANGED" | grep -E "\.($GAUNTLET_SOURCE_EXT)$" \
-        | grep -vE '(\.|_)(test|spec)\.[^.]+$|(^|/)tests?/|(^|/)\.stryker-tmp/' | while read -r f; do
+        | grep -vE "$TEST_RE|(^|/)\.stryker-tmp/" | while read -r f; do
           [ -f "$f" ] && printf '%s\n' "$f"
         done)
 
@@ -223,6 +223,7 @@ for owner in $OWNERS; do
   OWNED=$(while IFS= read -r f; do
             [ "$(owner_of "$f")" = "$owner" ] && printf '%s\n' "$f"
           done <<< "$FILES" | grep -vE "$GAUNTLET_NO_MUTATE" || true)
+  FCTX=""; if stryker_owner "$owner" "$OWNED"; then FCTX=$(files_context "$owner" "$OWNED"); files_split "$FCTX" "$owner" "$label"; fi
   [ -z "$OWNED" ] && continue
 
   # ONE comma-joined --mutate value, never a flag per range. Stryker's CLI
@@ -271,7 +272,7 @@ for owner in $OWNERS; do
     # 8 of them on one commit, all long since killed. --mutate already scopes
     # 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 --concurrency $(gate_workers) --mutate '${FLAGS#,}'"; stryker_page_tests "$base" "$label"
+    CMD="${RUN}$(stryker_bin "$base") run --concurrency $(gate_workers) --mutate '${FLAGS#,}'"; stryker_page_tests "$base" "$label"
   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
@@ -324,32 +325,9 @@ for owner in $OWNERS; do
   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
-  # HEADER every run and repeats the word in its table, so a bare grep reports
-  # survivors on a clean run — worse than not running at all. Stryker marks each
-  # real finding `[Survived]`; table and border lines are excluded outright.
-  # NoCoverage is printed exactly like Survived and means something worse: not
-  # "a test missed this mutation" but "no test executes this line at all". The
-  # gate matched only [Survived], so a diff whose files have no tests came back
-  # PASS — 306 uncovered mutants reported as proven on one commit. It is judged
-  # only for files that went in WITH a range: a glob-shaped path is mutated
-  # whole, so its untouched lines would report uncovered forever, and a finding
-  # nobody can close is what teaches people to --force.
-  #
-  # The status line carries no file name; the line under it does, as
-  # file:line:column. They are paired here rather than grepped separately.
   if [ "$TOOL" = stryker ]; then
-    ALL=$(printf '%s\n' "$OUT" | awk -v globbed="$GLOBBED" '
-      /^\[Survived\]/   { pend = $0; kind = "s"; next }
-      /^\[NoCoverage\]/ { pend = $0; kind = "n"; next }
-      pend != "" {
-        file = $0; sub(/:[0-9]+:[0-9]+$/, "", file)
-        if (kind == "s" || index(globbed, "," file ",") == 0) print pend "  " $0
-        pend = ""
-      }
-      # A survivor with no location under it is still a survivor, never dropped.
-      END { if (pend != "" && kind == "s") print pend }
-    ')
+    ALL=$(stryker_findings "$OUT" "$GLOBBED")
+    [ -n "$FCTX" ] && [ $RC -eq 0 ] && files_record "$FCTX" "$owner" "$ALL"
   else
     ALL=$(printf '%s\n' "$OUT" | grep -E '[Ss]urvived' \
           | grep -vE '^[[:space:]]*[#│|+-]|# *surviv')
@@ -433,7 +411,7 @@ for owner in $OWNERS; do
     STATUS=1
   elif [ $RC -ne 0 ]; then
     echo "  $label $TOOL (${T}s) — the run failed:"
-    printf '%s\n' "$OUT" | tail -12 | sed 's/^/      /'
+    printf '%s\n' "$OUT" | tail -12 | sed 's/^/      /'; stryker_elsewhere "$TOOL" "$base"
     [ "$STATUS" = 0 ] && STATUS=2
   elif [ -n "$NOTE" ]; then
     printf '%s\n' "$NOTE"

package/lib/setup-hook.mjs

@@ -28,6 +28,7 @@ const GAUNTLET_FILENAME = "gauntlet.sh";
 const SHIP_GATE_FILENAME = "ship-gate.sh";
 const SHIP_GATE_PROJECTS_FILENAME = "ship-gate-projects.sh";
 const SHIP_GATE_STRUCTURE_FILENAME = "ship-gate-structure.sh";
+const SHIP_GATE_FILES_FILENAME = "ship-gate-files.sh";
 const SHIP_GATE_HOOK_FILENAME = "ship-gate-hook.sh";
 const VERSION_CHECK_FILENAME = "version-check.sh";
 const LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
@@ -108,6 +109,7 @@ export async function setupHook(targetDir = process.cwd()) {
     SHIP_GATE_FILENAME,
     SHIP_GATE_PROJECTS_FILENAME,
     SHIP_GATE_STRUCTURE_FILENAME,
+    SHIP_GATE_FILES_FILENAME,
     SHIP_GATE_HOOK_FILENAME,
     VERSION_CHECK_FILENAME,
   ]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.45.0",
+  "version": "2.46.0",
   "description": "Guardrails for Claude Code — best-practice skills, planning commands, and delivery gates.",
   "type": "module",
   "repository": {
@@ -11,7 +11,7 @@
     "claude-skills": "bin/cli.mjs"
   },
   "scripts": {
-    "prepack": "cp ../README.md README.md && mkdir -p hooks && cp ../scripts/skill-gate.sh ../scripts/skill-gate-automark.sh ../scripts/skill-application-gate.sh ../scripts/gauntlet.sh ../scripts/ship-gate.sh ../scripts/ship-gate-projects.sh ../scripts/ship-gate-structure.sh ../scripts/ship-gate-hook.sh ../scripts/version-check.sh hooks/",
+    "prepack": "cp ../README.md README.md && mkdir -p hooks && cp ../scripts/skill-gate.sh ../scripts/skill-gate-automark.sh ../scripts/skill-application-gate.sh ../scripts/gauntlet.sh ../scripts/ship-gate.sh ../scripts/ship-gate-projects.sh ../scripts/ship-gate-structure.sh ../scripts/ship-gate-files.sh ../scripts/ship-gate-hook.sh ../scripts/version-check.sh hooks/",
     "postpack": "git checkout -- README.md && rm -rf hooks"
   },
   "engines": {