@boyingliu01/xp-gate 0.20.0 → 0.20.2

package/adapters/java.sh

@@ -1,10 +1,280 @@
 #!/usr/bin/env bash
+# ============================================================================
+# Java adapter -- GATE 1 static analysis (#507 S1, DR-001/DR-002)
+#
+# Primary engine: wc-java-lint (`check --staged --format json`), fail-closed:
+#   exit 0        -> PASS (clean)
+#   exit 1        -> FAIL (violations; never downgraded in soft mode)
+#   exit >=2      -> BLOCK (execution error / timeout / unusable JSON)
+#   JSON without the required whitelist fields (file/rule/severity) counts as
+#   unusable -> BLOCK; unknown extra fields are tolerated (additive evolution).
+# Escape valves:
+#   XP_GATE_WC_JAVA_LINT=soft   downgrades BLOCK-class outcomes (exit>=2,
+#     timeout, unusable JSON) to non-blocking WARN (exit 3); exit-1 stays FAIL.
+#   XP_GATE_WC_JAVA_LINT=report downgrades exit-1 violations to non-blocking
+#     WARN (rollout/grace mode for legacy repos; #507 Delphi round-1 C-MAJOR-3).
+#   An exit-0-with-objects response is a lying tool and is NEVER downgraded.
+# A SKIP/WARN reason crosses the subshell boundary as an `XP_G1_REASON: ...`
+# stdout line (export cannot: the caller captures command-substitution output).
+# Fallback: tool not on PATH -> legacy checkstyle/pmd + p3c/whalecloud chain;
+#   checkstyle AND pmd both missing -> explicit WARN and verdict must NOT be
+#   PASS (exit 3, recorded in the gate-1 audit detail).
+#
+# Verdict contract with pre-commit's `java)` branch:
+#   0 = PASS, 1 = FAIL(violations -> commit blocked), 2 = BLOCK(fail-closed),
+#   3 = WARN(non-blocking). pre-commit scores a WARN IN the denominator so it
+#   forbids an overall PASS -- Delphi round-2 A-MAJOR-1: mapping these paths
+#   to SKIP instead let unverified Java (no engine installed, or findings
+#   suppressed in report mode) ride out of the denominator to a fake 10/10.
+# ============================================================================
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # Plugin directory
 PLUGIN_DIR="$SCRIPT_DIR/plugins/p3c-java"
 WHALECLOUD_PLUGIN_DIR="$SCRIPT_DIR/plugins/whalecloud-java"
 
+WC_JAVA_LINT_DEFAULT_TIMEOUT=180
+
+# ---------------------------------------------------------------------------
+# Discovery (#507 AC-507-01-05): explicit multi-form support. MSYS2/Git Bash
+# `command -v` resolves .exe/.cmd only when the extension is spelled out, so
+# each form is probed verbatim.
+# ---------------------------------------------------------------------------
+wc_java_lint_bin() {
+  local candidate
+  for candidate in wc-java-lint wc-java-lint.exe wc-java-lint.cmd; do
+    if command -v "$candidate" >/dev/null 2>&1; then
+      command -v "$candidate"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# ---------------------------------------------------------------------------
+# Timeout (#507 AC-507-01-09): .xp-gate/wc-java-lint-timeout (positive
+# integer seconds) > default 180. Invalid values WARN and fall back -- an
+# unreadable override must not silently disable the timeout.
+# ---------------------------------------------------------------------------
+resolve_wc_java_lint_timeout() {
+  local file=".xp-gate/wc-java-lint-timeout" val=""
+  if [ -f "$file" ]; then
+    val=$(tr -d '[:space:]' < "$file")
+  fi
+  if [ -z "$val" ]; then
+    echo "$WC_JAVA_LINT_DEFAULT_TIMEOUT"
+    return 0
+  fi
+  case "$val" in
+    ''|*[!0-9]*|0)
+      echo "WARN - invalid $file value '${val}' (expected a positive integer), falling back to ${WC_JAVA_LINT_DEFAULT_TIMEOUT}s" >&2
+      echo "$WC_JAVA_LINT_DEFAULT_TIMEOUT"
+      ;;
+    *) echo "$val" ;;
+  esac
+}
+
+# ---------------------------------------------------------------------------
+# Staged .java file set (#507 AC-507-01-10): the ONLY files handed to the
+# tool in explicit-list mode. Polyglot commits keep their TS/Python files out
+# of the Java engine entirely.
+# ---------------------------------------------------------------------------
+java_staged_files() {
+  # Harness/test injection: XP_GATE_JAVA_STAGED_FILES supplies a raw file
+  # list (newline-separated) so tests can exercise the .java filter without
+  # a git repo. The filter still applies -- the tool never sees non-.java.
+  if [ -n "${XP_GATE_JAVA_STAGED_FILES:-}" ]; then
+    printf '%s\n' "$XP_GATE_JAVA_STAGED_FILES" | grep -E '\.java$' || true
+    return 0
+  fi
+  git diff --cached --name-only --diff-filter=d 2>/dev/null \
+    | grep -E '\.java$' || true
+}
+
+# ---------------------------------------------------------------------------
+# JSON whitelist validation (#507 AC-507-01-07, DR-002).
+# Contract shape: a JSON array of FLAT violation objects, each carrying
+# file/rule/severity (line optional). Checks are grep-based by design:
+#   - STRING LITERALS ARE STRIPPED BEFORE COUNTING (#507 Delphi round-1
+#     A-MAJOR-1): violation messages routinely contain braces ("'{' is not
+#     preceded...") or the words file/rule/severity -- counting raw text made
+#     perfectly valid output false-BLOCK. After stripping, only structural
+#     braces and structural keys remain.
+#   - unknown extra fields add occurrences of their own keys, never remove
+#     the required ones -> tolerated (additive evolution);
+#   - any object missing a required key desynchronizes the per-key occurrence
+#     counts from the object count -> unusable -> BLOCK;
+#   - a truncated response (no closing bracket) is unusable -> BLOCK.
+# Prints the violation (object) count on success; returns 1 if unusable.
+# ---------------------------------------------------------------------------
+wc_java_json_violation_count() {
+  local json_file="$1"
+  [ -s "$json_file" ] || return 1
+
+  # Array-shaped: opens with [ and closes with ]. (A bare [] is valid clean
+  # output; an object wrapper is outside the pinned contract.)
+  [ "$(head -c 1 "$json_file")" = "[" ] || return 1
+  local tail
+  tail=$(tr -d '[:space:]' < "$json_file" | tail -c 1)
+  [ "$tail" = "]" ] || return 1
+
+  # Strip string VALUE literals (`: "..."` -> `: ""`). Keys must survive
+  # (they are the tokens being counted); values must vanish (violation
+  # messages routinely contain braces or the words file/rule/severity --
+  # #507 Delphi round-1 A-MAJOR-1). JSON strings cannot contain raw newlines
+  # (they are \n escapes), so line-wise sed is safe. The leftmost-match rule
+  # consumes an entire value string in one go, including any `: "` sequences
+  # inside it. Broken JSON masks badly -> counts desynchronize -> BLOCK,
+  # which is the correct fail-closed direction.
+  # POSIX ERE via -E: BSD sed (macOS is a supported CI platform) does not
+  # support the GNU BRE `\|` alternation extension -- under BSD sed the GNU
+  # variant either fails to strip values (count desync -> BLOCK, annoying but
+  # safe) or, worst case, errors to empty counts and disarms the lying-tool
+  # BLOCK below (fail-open). Delphi round-2 A-MAJOR-2.
+  local structural obj_count file_count rule_count sev_count
+  structural=$(sed -E 's/:([[:space:]]*)"([^"\\]|\\.)*"/:\1""/g' "$json_file" 2>/dev/null)
+  obj_count=$(grep -o '{' <<< "$structural" | wc -l | tr -d '[:space:]')
+  file_count=$(grep -o '"file"' <<< "$structural" | wc -l | tr -d '[:space:]')
+  rule_count=$(grep -o '"rule"' <<< "$structural" | wc -l | tr -d '[:space:]')
+  sev_count=$(grep -o '"severity"' <<< "$structural" | wc -l | tr -d '[:space:]')
+  [ "$obj_count" -eq "$file_count" ] || return 1
+  [ "$obj_count" -eq "$rule_count" ] || return 1
+  [ "$obj_count" -eq "$sev_count" ] || return 1
+
+  echo "$obj_count"
+}
+
+# Distinct staged-file names from a violations JSON (reporting only).
+wc_java_json_files() {
+  grep -o '"file"[[:space:]]*:[[:space:]]*"[^"]*"' "$1" 2>/dev/null \
+    | sed 's/.*"\([^"]*\)"$/\1/' | sort -u | head -10
+}
+
+# ---------------------------------------------------------------------------
+# Primary engine (#507 AC-507-01-01/02/06/09).
+# Prints a human-readable report on stdout; returns the verdict code.
+# ---------------------------------------------------------------------------
+run_wc_java_lint() {
+  local bin="" timeout_s out_file err_file exit_code count
+
+  if ! bin=$(wc_java_lint_bin); then
+    return 9  # not installed -> caller falls back to the legacy chain
+  fi
+
+  timeout_s=$(resolve_wc_java_lint_timeout)
+  out_file=$(mktemp "${TMPDIR:-/tmp}/wc-java-lint.XXXXXX")
+  err_file="${out_file}.err"
+
+  # Primary contract call: the tool inspects the index itself.
+  # `|| exit_code=$?` keeps a non-zero verdict from killing the host when
+  # this module is sourced into a `set -e` consumer (repo convention,
+  # cf. gate-4.sh's `|| PRINCIPLES_EXIT=$?`).
+  exit_code=0
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$timeout_s" "$bin" check --staged --format json >"$out_file" 2>"$err_file" || exit_code=$?
+  else
+    echo "     ⚠️  'timeout' command not available - running wc-java-lint without a timeout guard" >&2
+    "$bin" check --staged --format json >"$out_file" 2>"$err_file" || exit_code=$?
+  fi
+
+  # Usage-error fallback (#507 AC-507-01-06): an older build without --staged
+  # answers with a usage message and exit>=2. Retry with the explicit staged
+  # .java list; any OTHER exit>=2 stays an execution error.
+  if [ "$exit_code" -ge 2 ] \
+     && grep -qiE 'unknown option|unrecognized option|^usage' "$err_file" "$out_file" 2>/dev/null; then
+    local staged_args=()
+    while IFS= read -r jf; do
+      [ -n "$jf" ] && staged_args+=("$jf")
+    done <<< "$(java_staged_files)"
+    if [ "${#staged_args[@]}" -gt 0 ]; then
+      exit_code=0
+      if command -v timeout >/dev/null 2>&1; then
+        timeout "$timeout_s" "$bin" check --format json "${staged_args[@]}" >"$out_file" 2>"$err_file" || exit_code=$?
+      else
+        "$bin" check --format json "${staged_args[@]}" >"$out_file" 2>"$err_file" || exit_code=$?
+      fi
+    fi
+  fi
+
+  if [ -s "$err_file" ]; then
+    sed 's/^/     /' "$err_file"
+  fi
+
+  case "$exit_code" in
+    0)
+      if ! count=$(wc_java_json_violation_count "$out_file"); then
+        echo "❌ wc-java-lint output is not a usable violations JSON (fail-closed, #507 DR-001)"
+        rm -f "$out_file" "$err_file"
+        if [ "${XP_GATE_WC_JAVA_LINT:-}" = "soft" ]; then
+          # Unusable output IS an execution-class failure (the tool exists but
+          # its response cannot be trusted) -- same class as exit>=2, covered
+          # by the escape valve (#507 Delphi round-1 B-MAJOR-5).
+          echo "⚠️  XP_GATE_WC_JAVA_LINT=soft: unusable JSON downgraded to WARN (non-blocking, in scoring denominator)"
+          echo "XP_G1_REASON: wc-java-lint unusable JSON (soft downgrade)"
+          return 3
+        fi
+        return 2
+      fi
+      if [ "$count" -gt 0 ]; then
+        # Contract says exit 0 means clean; objects + 0 is a LYING tool, not a
+        # broken one. It claims success while reporting violations -- there is
+        # no trustworthy interpretation, so soft/report must NOT downgrade it
+        # (deliberately outside the escape valve; #507 Delphi round-1 B-MAJOR-5).
+        echo "❌ wc-java-lint exited 0 but reported $count violation object(s) - inconsistent response"
+        rm -f "$out_file" "$err_file"
+        return 2
+      fi
+      rm -f "$out_file" "$err_file"
+      echo "✅ wc-java-lint: clean"
+      return 0
+      ;;
+    1)
+      if count=$(wc_java_json_violation_count "$out_file"); then
+        echo "❌ wc-java-lint: $count violation(s) in:"
+        wc_java_json_files "$out_file" | sed 's/^/       /'
+      else
+        echo "❌ wc-java-lint reported violations but the JSON was unusable"
+      fi
+      rm -f "$out_file" "$err_file"
+      if [ "${XP_GATE_WC_JAVA_LINT:-}" = "report" ]; then
+        # Rollout/grace mode (#507 Delphi round-1 C-MAJOR-3): a legacy repo
+        # adopting wc-java-lint carries pre-existing violations; hard-blocking
+        # every commit gives no migration path. report mode degrades REAL
+        # violations to non-blocking WARN -- pre-commit scores WARN in the
+        # denominator and an overall WARN verdict forbids a PASS (Delphi
+        # round-2 A-MAJOR-1: SKIP would have produced a fake 10/0 for a
+        # repo whose only Java check is suppressed), so teams burn down
+        # findings before switching back to enforcing.
+        echo "⚠️  XP_GATE_WC_JAVA_LINT=report: violations downgraded to WARN (rollout mode)"
+        echo "⚠️  Java code quality NOT enforcing - burn down the findings, then unset report mode"
+        echo "XP_G1_REASON: wc-java-lint report mode: ${count:-unknown} violation(s) suppressed"
+        return 3
+      fi
+      return 1
+      ;;
+    *)
+      rm -f "$out_file" "$err_file"
+      if [ "$exit_code" -eq 124 ]; then
+        echo "❌ wc-java-lint timed out after ${timeout_s}s"
+      else
+        echo "❌ wc-java-lint failed with exit code $exit_code"
+      fi
+      if [ "${XP_GATE_WC_JAVA_LINT:-}" = "soft" ]; then
+        echo "⚠️  XP_GATE_WC_JAVA_LINT=soft: execution failure downgraded to WARN (non-blocking, #507 DR-001 escape valve)"
+        echo "⚠️  Java static analysis NOT performed - the engine exists but is broken; do not treat this as a clean run"
+        # The reason crosses the command-substitution subshell boundary via a
+        # prefixed stdout line (export does NOT: the caller captures this
+        # function's output, so the subshell env is discarded -- #507 Delphi
+        # round-1 B-MAJOR-1). pre-commit parses and strips the line.
+        echo "XP_G1_REASON: wc-java-lint broken (soft downgrade)"
+        return 3
+      fi
+      return 2
+      ;;
+  esac
+}
+
+# ---------------------------------------------------------------------------
 _is_whalecloud_enabled() {
   # Check if whalecloud-java plugin is enabled
   [ -d "$WHALECLOUD_PLUGIN_DIR" ] && \
@@ -22,40 +292,74 @@ _detect_java_build() {
   fi
 }
 
-run_static_analysis() {
-  local build_system
+# ---------------------------------------------------------------------------
+# Legacy fallback (#507 AC-507-01-03): only reached when wc-java-lint is not
+# installed. Prints one WARN per missing plugin dir; if neither checkstyle
+# nor pmd is available the verdict must NOT be PASS (exit 3, audit warn).
+# ---------------------------------------------------------------------------
+run_legacy_analysis() {
+  local build_system lint_tools=0 worst=0 rc=0
+
   build_system=$(_detect_java_build)
 
-  if [ "$build_system" = "maven" ]; then
-    mvn compile -q 2>&1 | grep -i "error\|fail" | sed -n '1,5p; 5q'
-    if [ "${PIPESTATUS[0]}" -ne 0 ]; then
-      echo "❌ Maven compilation failed"
-      return 1
-    fi
-  elif [ "$build_system" = "gradle" ]; then
-    gradle compileJava --quiet 2>&1 | grep -i "error\|fail" | sed -n '1,5p; 5q'
-    if [ "${PIPESTATUS[0]}" -ne 0 ]; then
-      echo "❌ Gradle compilation failed"
-      return 1
-    fi
+  if [ ! -d "$PLUGIN_DIR" ]; then
+    echo "⚠️  p3c-java plugin directory missing: $PLUGIN_DIR"
   fi
+  if [ ! -d "$WHALECLOUD_PLUGIN_DIR" ]; then
+    echo "⚠️  whalecloud-java plugin directory missing: $WHALECLOUD_PLUGIN_DIR"
+  fi
+
+  # Every engine's verdict is AGGREGATED (#507 blind review MAJOR-1): a tool
+  # that reports violations must never degrade to a silent PASS -- that was
+  # the exact anti-pattern this sprint exists to remove.
+  local out_file
+  out_file=$(mktemp "${TMPDIR:-/tmp}/java-legacy.XXXXXX")
 
   # CheckStyle with Google style (legacy fallback)
   if command -v checkstyle &>/dev/null; then
-    checkstyle -c /google_checks.xml . 2>&1 | sed -n '1,20p; 20q'
+    lint_tools=$((lint_tools + 1))
+    rc=0
+    checkstyle -c /google_checks.xml . >"$out_file" 2>&1 || rc=$?
+    sed -n '1,20p' "$out_file"
+    [ "$rc" -ne 0 ] && worst=1
   fi
 
   # PMD error detection (legacy fallback)
   if command -v pmd &>/dev/null; then
-    pmd check -d . -R category/java/errorprone.xml 2>&1 | sed -n '1,20p; 20q'
+    lint_tools=$((lint_tools + 1))
+    rc=0
+    pmd check -d . -R category/java/errorprone.xml >"$out_file" 2>&1 || rc=$?
+    sed -n '1,20p' "$out_file"
+    [ "$rc" -ne 0 ] && worst=1
+  fi
+  rm -f "$out_file"
+
+  if [ "$lint_tools" -eq 0 ]; then
+    echo "⚠️  No Java static-analysis engine available: wc-java-lint, checkstyle and pmd all missing"
+    echo "⚠️  Java code quality NOT verified - verdict is WARN, not PASS (#507 AC-507-01-03)"
+    echo "   Install wc-java-lint (preferred) or checkstyle/pmd to restore verification"
+    _XP_JAVA_LEGACY_WARN=1
+    echo "XP_G1_REASON: legacy tools unavailable (warn)"
   fi
 
   # p3c-pmd check (Alibaba coding guidelines) — primary Java quality gate
-  _run_p3c_check "$build_system"
+  # (`-Dpmd.failOnViolation=true` makes violations exit non-zero).
+  rc=0
+  _run_p3c_check "$build_system" || rc=$?
+  [ "$rc" -ne 0 ] && worst=1
 
   # WhaleCloud Java Coding Standards — overlay on top of p3c-pmd
-  _run_whalecloud_check "$build_system"
+  rc=0
+  _run_whalecloud_check "$build_system" || rc=$?
+  [ "$rc" -ne 0 ] && worst=1
 
+  if [ "$worst" -ne 0 ]; then
+    echo "  ❌ legacy Java analysis found violations"
+    return 1
+  fi
+  if [ "${_XP_JAVA_LEGACY_WARN:-0}" = "1" ]; then
+    return 3
+  fi
   return 0
 }
 
@@ -128,6 +432,21 @@ run_p3c_check() {
   _run_p3c_check "$(_detect_java_build)"
 }
 
+# Legacy maven/gradle invocations are network-facing (plugin/rule resolution
+# against remote repositories). Without a guard a cold cache can hang
+# pre-commit for minutes (#507 Delphi round-1 C-MAJOR-2; round-2 extended the
+# same guard to the Gradle legacy lint calls). Same timeout file as the
+# primary engine: .xp-gate/wc-java-lint-timeout. Degrades safely when
+# `timeout` is unavailable (rc 127 must never be mistaken for a tool verdict).
+_legacy_build_run() {
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$(resolve_wc_java_lint_timeout)" "$@"
+  else
+    echo "     ⚠️  'timeout' command not available - legacy build-tool call runs unguarded" >&2
+    "$@"
+  fi
+}
+
 _run_p3c_check() {
   local build_system="$1"
 
@@ -135,13 +454,20 @@ _run_p3c_check() {
 
   if [ "$build_system" = "maven" ]; then
     if grep -q '<id>xp-gate-p3c</id>' pom.xml 2>/dev/null; then
-      # Profile already installed — use it
-      mvn pmd:check -P xp-gate-p3c -Dpmd.failOnViolation=true 2>&1 | tail -30
+      # Profile already installed — use it (timeout-guarded: legacy maven
+      # resolves plugins/rulesets over the network, a cold cache must not
+      # hang pre-commit unbounded -- #507 Delphi round-1 C-MAJOR-2)
+      _legacy_build_run mvn pmd:check -P xp-gate-p3c -Dpmd.failOnViolation=true 2>&1 | tail -30
       return "${PIPESTATUS[0]}"
     else
-      # Profile not installed — run inline with p3c-pmd dependency
-      if command -v mvn &>/dev/null; then
-        mvn pmd:check \
+      # Profile not installed. The inline ruleset paths (/rulesets/java/ali-*)
+      # resolve INSIDE the p3c-pmd jar — without that dependency in the pom,
+      # maven cannot resolve them and exits non-zero, which BLOCKed the commit
+      # on every real project without p3c configured (#507 Delphi round-1
+      # C-MAJOR-1). "Not configured" is an opt-out, not a violation: only run
+      # inline when the pom actually declares p3c-pmd.
+      if grep -q 'p3c-pmd' pom.xml 2>/dev/null; then
+        _legacy_build_run mvn pmd:check \
           -Dpmd.rulesets="/rulesets/java/ali-comment.xml,/rulesets/java/ali-concurrent.xml,/rulesets/java/ali-constant.xml,/rulesets/java/ali-exception.xml,/rulesets/java/ali-flowcontrol.xml,/rulesets/java/ali-naming.xml,/rulesets/java/ali-oop.xml,/rulesets/java/ali-orm.xml,/rulesets/java/ali-other.xml,/rulesets/java/ali-set.xml" \
           -Dpmd.failOnViolation=true \
           -DprintFailingErrors=true \
@@ -158,7 +484,8 @@ _run_p3c_check() {
         echo "  ✅ p3c-pmd check passed"
         return 0
       else
-        echo "  ℹ️  Maven not available — Skipping p3c-pmd"
+        echo "  ℹ️  p3c-pmd not configured in pom.xml — skipping (opt-in, not a violation)"
+        echo "  To enable: bash $PLUGIN_DIR/scripts/install-maven-p3c.sh"
         return 0
       fi
     fi
@@ -166,7 +493,7 @@ _run_p3c_check() {
   elif [ "$build_system" = "gradle" ]; then
     if grep -q 'xp-gateP3cCheck\|p3c-pmd' build.gradle 2>/dev/null || \
        grep -q 'xp-gateP3cCheck\|p3c-pmd' build.gradle.kts 2>/dev/null; then
-      gradle xp-gateP3cCheck --quiet 2>&1 | tail -20
+      _legacy_build_run gradle xp-gateP3cCheck --quiet 2>&1 | tail -20
       return "${PIPESTATUS[0]}"
     else
       echo "  ℹ️  p3c-pmd not configured in Gradle build"
@@ -190,7 +517,8 @@ _run_whalecloud_check() {
 
   if [ "$build_system" = "maven" ]; then
     if grep -q '<id>xp-gate-whalecloud-java</id>' pom.xml 2>/dev/null; then
-      mvn pmd:check checkstyle:check spotbugs:check \
+      # timeout-guarded, same rationale as the p3c branch (C-MAJOR-2)
+      _legacy_build_run mvn pmd:check checkstyle:check spotbugs:check \
         -P xp-gate-whalecloud-java -Dpmd.failOnViolation=true \
         2>&1 | tail -30
       return "${PIPESTATUS[0]}"
@@ -203,7 +531,7 @@ _run_whalecloud_check() {
   elif [ "$build_system" = "gradle" ]; then
     if grep -q 'xp-gateWhalecloudCheck' build.gradle 2>/dev/null || \
        grep -q 'xp-gateWhalecloudCheck' build.gradle.kts 2>/dev/null; then
-      gradle xp-gateWhalecloudCheck --quiet 2>&1 | tail -20
+      _legacy_build_run gradle xp-gateWhalecloudCheck --quiet 2>&1 | tail -20
       return "${PIPESTATUS[0]}"
     else
       echo "  ⚠️  whalecloud-java not configured in Gradle build"
@@ -218,3 +546,21 @@ _run_whalecloud_check() {
 run_whalecloud_check() {
   _run_whalecloud_check "$(_detect_java_build)"
 }
+
+# ---------------------------------------------------------------------------
+# GATE 1 entry (#507 S1). wc-java-lint first; legacy chain only on discovery
+# miss. The old direct mvn/gradle compile here moved to Build Integrity (S5).
+# ---------------------------------------------------------------------------
+run_static_analysis() {
+  local rc=0
+  # `|| rc=$?` (not a bare call): under a set -e consumer a non-zero verdict
+  # would otherwise abort the host hook instead of returning the verdict code.
+  run_wc_java_lint || rc=$?
+  if [ "$rc" -eq 9 ]; then
+    echo "ℹ️  wc-java-lint not found - falling back to legacy Java analysis"
+    rc=0
+    run_legacy_analysis || rc=$?
+    return "$rc"
+  fi
+  return "$rc"
+}

package/adapters/powershell.sh

@@ -190,17 +190,72 @@ run_coverage() {
       source_files[${#source_files[@]}]="$path"
     done < "$discovery_file"
     rm -f "$discovery_file"
+
+    # Optional project-level exclusions. Some scripts cannot be instrumented or
+    # exercised by a unit-test runner at all (e.g. a bootstrap script whose Main
+    # ends in `exit`, which terminates the Pester host when invoked in-process).
+    # Counting them as 0% coverage permanently caps the achievable percentage and
+    # makes the threshold unsatisfiable no matter how good the suite is.
+    # Format: one glob per line in .xp-gate-powershell-coverage-ignore
+    local ignore_file=".xp-gate-powershell-coverage-ignore"
+    if [ -f "$ignore_file" ]; then
+      local filtered=()
+      local src
+      for src in "${source_files[@]}"; do
+        local skip=0
+        local pat
+        # Discovery yields paths like "./setup.ps1"; match the pattern against the
+        # raw path AND the "./"-stripped form so a plain "setup.ps1" glob works.
+        local src_norm="${src#./}"
+        while IFS= read -r pat; do
+          # skip blanks and comments
+          case "$pat" in ''|'#'*) continue ;; esac
+          local pat_norm="${pat#./}"
+          # shellcheck disable=SC2254
+          case "$src" in $pat|$pat_norm) skip=1; break ;; esac
+          # shellcheck disable=SC2254
+          case "$src_norm" in $pat_norm) skip=1; break ;; esac
+        done < "$ignore_file"
+        if [ "$skip" -eq 0 ]; then
+          filtered[${#filtered[@]}]="$src"
+        else
+          echo "  ℹ️  Coverage exclusion matched: $src"
+        fi
+      done
+      # Assign back unconditionally: when EVERY source file matched an
+      # exclusion, `filtered` is empty and the check below must see 0 to skip
+      # coverage. Only assigning on >0 silently ignored a full exclusion.
+      # (Empty-array guards keep this bash-3.2 / `set -u` safe.)
+      if [ "${#filtered[@]}" -gt 0 ]; then
+        source_files=("${filtered[@]}")
+      else
+        source_files=()
+      fi
+    fi
+
+    if [ "${#source_files[@]}" -eq 0 ]; then
+      echo "No PowerShell source files left after exclusions, skipping coverage"
+      return 0
+    fi
+
     test_paths=$(_powershell_path_array "${test_files[@]}")
     coverage_paths=$(_powershell_path_array "${source_files[@]}")
     echo "Running Pester with code coverage..."
+    # Pester 5 requires the modern configuration object: `-Path ... -CodeCoverage ...`
+    # is the deprecated Pester 4 parameter set and fails outright on Pester 5.x
+    # ("cannot resolve parameter set"). Using it silently produced no coverage.xml,
+    # which the pre-commit hook then reported as an unparseable/zero result.
     _pester_timeout "$PWSH" "${POWERSHELL_ARGS[@]}" "
-      \$results = Invoke-Pester -Path $test_paths -CodeCoverage $coverage_paths -PassThru
+      \$cfg = New-PesterConfiguration
+      \$cfg.Run.Path = $test_paths
+      \$cfg.CodeCoverage.Enabled = \$true
+      \$cfg.CodeCoverage.Path = $coverage_paths
+      \$cfg.CodeCoverage.OutputFormat = 'JaCoCo'
+      \$cfg.CodeCoverage.OutputPath = (Join-Path (Get-Location) 'coverage.xml')
+      \$cfg.Run.PassThru = \$true
+      \$results = Invoke-Pester -Configuration \$cfg
       \$pct = [math]::Round(\$results.CodeCoverage.CoveragePercent, 1)
       Write-Host \"Coverage: \$pct%\"
-      if (\$pct -lt 80) {
-        Write-Host \"WARNING: Coverage \$pct% is below 80% threshold\"
-        exit 0
-      }
       exit 0
     " 2>&1
     local cov_exit=$?

package/adapters/python.sh

@@ -4,13 +4,33 @@
 # Tools: mypy, ruff/flake8, pytest, import-linter (architecture)
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# SC1091：adapter-common.sh 由调用方按查找顺序提供，路径靠变量拼接，shellcheck 无法静态跟随。
+# `source … || true` 是既有容错口径（仓库存档时该文件可能不在），不要改成硬依赖。
+# shellcheck source=/dev/null
 source "$SCRIPT_DIR/../adapter-common.sh" 2>/dev/null || true
 
 run_static_analysis() {
   require_tool mypy "mypy" || return 1
 
+  # 口径 = CI type job（.github/workflows/ci.yml:43-45）的两条命令，逐字一致。
+  # 为什么不能写 `mypy .`：`.` 会递归扫到两类文件，而它们在仓库里从未被声明为
+  # 门禁面，CI 也从不检查：
+  #   ① 根目录一次性调研/演示脚本（fetch_*.py、demo_*.py、validate_*.py 等）——
+  #      `[tool.ruff] exclude`（pyproject.toml:217-238）已逐文件把它们列为"历史产物，
+  #      从未被 `ruff check src/ tests/` 覆盖"，mypy 侧却没有对应排除；
+  #   ② `tests/` —— CI 只跑 `mypy src/` 与 `mypy scripts/`，测试域的类型问题
+  #      没有任何门禁核对过。
+  # 两份清单不一致的后果是钩子恒红且与本仓任何真实缺陷无关：实测 `mypy .` 87 条
+  # error（本机），而 `mypy src/`（136 files）与 `mypy scripts/`（42 files）各自
+  # exit 0。即当时钩子会阻断**任何**提交，包括纯文档改动。
+  # 处置是让钩子对齐已声明的 CI 口径，而不是给那 87 处补注解——补注解既不在声明
+  # 口径内，又会顺手动几十个无关文件（含 tests/）。
+  # 口径一致性由仓库侧 BATS 测试双向锁住：
+  # githooks/__tests__/adapter-mypy-pester-scope.test.bats（含"适配器里不得再
+  # 出现裸 mypy ."），防止 `mypy .` 被写回来时无人报警。
   echo "Running Python static analysis (mypy)..."
-  mypy .
+  mypy src/ || return 1
+  mypy scripts/
   return $?
 }
 
@@ -45,7 +65,8 @@ run_tests() {
   require_tool pytest "pytest" || return 1
 
   echo "Running Python tests..."
-  PYTEST_OUTPUT=$(pytest --exitfirst --tb=short 2>&1)
+  # Skip e2e tests by default in pre-commit (require live API + network)
+  PYTEST_OUTPUT=$(pytest --exitfirst --tb=short -m "not e2e" 2>&1)
   PYTEST_EXIT=$?
 
   # Show the short summary tail — this is where FAILED/assert diagnostics live.
@@ -85,7 +106,10 @@ run_coverage() {
   require_tool pytest "pytest" || return 1
 
   echo "Running Python coverage..."
-  PYTEST_OUTPUT=$(pytest --exitfirst --tb=short --cov=. --cov-fail-under=80 2>&1)
+  # 阈值不在此处硬编码：pytest-cov 自动读取 pyproject.toml 的
+  # [tool.coverage.report] fail_under（唯一事实源）。此前这里重复写了
+  # --cov-fail-under=79.9，改 pyproject 不会让门禁跟着变，属于假配置。
+  PYTEST_OUTPUT=$(pytest --exitfirst --tb=short --cov=src -m "not e2e" 2>&1)
   PYTEST_EXIT=$?
   echo "$PYTEST_OUTPUT" | grep -E "(FAILED|PASSED|passed|failed|error|ERROR|TOTAL|assert)" | tail -10
   echo "$PYTEST_OUTPUT" | tail -5
@@ -152,7 +176,17 @@ run_mutation() {
   local MUTATION_OUTPUT
   MUTATION_OUTPUT=$(mktemp)
 
-  timeout "${timeout_s}s" mutmut run --paths-to-mutate $file_list > "$MUTATION_OUTPUT" 2>&1
+  local MUTMUT_CMD="mutmut"
+  if ! command -v mutmut >/dev/null 2>&1; then
+    MUTMUT_CMD="python3 -m mutmut"
+  fi
+
+  # SC2086：`$MUTMUT_CMD` 与 `$file_list` 都是**故意按空白分词**的——
+  # 前者可能是两个词（`python3 -m mutmut`），后者是空格分隔的多条路径，
+  # 加引号会把它们并成单个参数、直接让命令失败。故此处显式声明意图，
+  # 而不是改成引号（引号在这里不是修 bug，是造 bug）。
+  # shellcheck disable=SC2086
+  timeout "${timeout_s}s" $MUTMUT_CMD run --paths-to-mutate $file_list > "$MUTATION_OUTPUT" 2>&1
   local EXIT_CODE=$?
 
   cat "$MUTATION_OUTPUT"