@boyingliu01/xp-gate 0.20.1 → 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/gate-3.sh

@@ -1,3 +1,4 @@
+# shellcheck shell=bash
 # ============================================================================
 # GATE 3: Cyclomatic Complexity Check
 # Uses lizard - checks cyclomatic complexity of changed source files
@@ -17,7 +18,45 @@ elif [ "$PROJECT_LANG" = "powershell" ]; then
   GATE_3_STATUS="SKIP"
   
 else
-  CCN_THRESHOLD=5
+  # S2 (#507): three-level CCN threshold override --
+  # .xp-gate/ccn-threshold (positive integer) > XP_GATE_CCN_THRESHOLD > 5.
+  # Invalid values WARN on stderr and fall back to the default; the resolved
+  # value reaches the gate-3 audit record via the --detail argument below.
+  # Implemented with bash builtins only (no tr/grep spawns): every process
+  # spawn is expensive on Windows under AV filter drivers.
+  resolve_ccn_threshold() {
+    local default=5 val
+    if [ -f ".xp-gate/ccn-threshold" ]; then
+      val=$(<".xp-gate/ccn-threshold")
+      val="${val//[[:space:]]/}"
+      case "$val" in
+        ''|*[!0-9]*|0)
+          echo "WARN - invalid .xp-gate/ccn-threshold value '${val}' (expected a positive integer), falling back to ${default}" >&2
+          ;;
+        *)
+          echo "$val"
+          return 0
+          ;;
+      esac
+      echo "$default"
+      return 0
+    fi
+    val=${XP_GATE_CCN_THRESHOLD:-}
+    if [ -n "$val" ]; then
+      case "$val" in
+        ''|*[!0-9]*|0)
+          echo "WARN - invalid XP_GATE_CCN_THRESHOLD value '${val}' (expected a positive integer), falling back to ${default}" >&2
+          ;;
+        *)
+          echo "$val"
+          return 0
+          ;;
+      esac
+    fi
+    echo "$default"
+  }
+
+  CCN_THRESHOLD=$(resolve_ccn_threshold)
   
   # Check lizard availability
   LIZARD_CMD=""
@@ -37,7 +76,16 @@ else
       echo "Checking complexity for source files..."
       
       # Run lizard with CCN threshold
-      CC_OUTPUT=$($LIZARD_PATH -C $CCN_THRESHOLD $CC_FILES 2>&1 || true)
+      # One path per line, into an array. Unquoted $CC_FILES relied on word
+      # splitting, which also splits any path containing a space -- handing
+      # lizard two bogus paths and checking neither (#457 defect class, same
+      # fix as gate-4's PRINCIPLES_ARGS). Quoting the scalar would instead
+      # collapse the list into one argument. An array does both.
+      CC_FILES_ARGS=()
+      while IFS= read -r _cc_file; do
+        [ -n "$_cc_file" ] && CC_FILES_ARGS+=("$_cc_file")
+      done <<< "$CC_FILES"
+      CC_OUTPUT=$("$LIZARD_PATH" -C "$CCN_THRESHOLD" ${CC_FILES_ARGS[@]+"${CC_FILES_ARGS[@]}"} 2>&1 || true)
       
       # Parse warning count from the summary table: "Warning cnt   8"
       # Use anchored grep to avoid matching lizard table headers (e.g. "Rt" column)
@@ -65,4 +113,4 @@ else
     GATE_3_STATUS="WARN"
   fi
 fi
-record_gate_audit "gate-3" "complexity" "$GATE_3_STATUS" "${CC_WARNINGS:-0}" "$GATE_3_START"
+record_gate_audit "gate-3" "complexity" "$GATE_3_STATUS" "${CC_WARNINGS:-0}" "$GATE_3_START" "ccn_threshold=${CCN_THRESHOLD:-5}"

package/gate-4.sh

@@ -1,3 +1,4 @@
+# shellcheck shell=bash
 # ============================================================================
 # GATE 4: Principles Checker (Clean Code + SOLID)
 # Reuses existing principles checker logic
@@ -23,6 +24,31 @@ if ! declare -F run_tsx >/dev/null 2>&1; then
   }
 fi
 
+# Java rule coverage annotation (#507 S4, AC-507-04-02). The normative matrix
+# lives in docs/java-principles-coverage.md; these constants mirror it. Before
+# #507 the Java adapter fed rules only {name,type,line,code}, so the 12 rules
+# reading structured metrics silently saw `undefined` and a Java commit got a
+# green "checked" with zero effective coverage. 12/15 now fire; the three
+# inert ones are rule-side gaps documented in the coverage doc -- they must
+# NOT be announced as covered.
+JAVA_COVERAGE_EFFECTIVE=12
+JAVA_COVERAGE_TOTAL=15
+JAVA_COVERAGE_INERT="lsp, many-exports, code-duplication"
+
+# Print the coverage annotation when (and only when) the staged file list
+# contains Java sources. Non-Java commits keep the original output byte for
+# byte. Pure shell builtins: no subprocess per file.
+java_coverage_note() {
+  local _f _has_java=""
+  for _f in "$@"; do
+    case "$_f" in
+      *.java|*.Java|*.JAVA) _has_java=1; break ;;
+    esac
+  done
+  [ -n "$_has_java" ] || return 0
+  echo "ℹ️  Java rule coverage: $JAVA_COVERAGE_EFFECTIVE/$JAVA_COVERAGE_TOTAL rules effective (inert on Java: $JAVA_COVERAGE_INERT -- see docs/java-principles-coverage.md)"
+}
+
  2>&1 echo ""
  2>&1 echo "→ Gate 4: Principles checker (Clean Code + SOLID)..."
 GATE_4_START=$(gate_start_ms)
@@ -72,7 +98,12 @@ else
     
     if [ -n "$PRINCIPLES_DIR" ]; then
       echo "Checking Clean Code + SOLID principles..."
-      
+
+      # AC-507-04-02: say what a Java commit is actually covered for, instead
+      # of implying a full 15-rule check (#507). Printed before the run so it
+      # appears on both the PASS and the FAIL path.
+      java_coverage_note ${PRINCIPLES_ARGS[@]+"${PRINCIPLES_ARGS[@]}"}
+
       if command -v npx > /dev/null 2>&1 || [ -f "$PRINCIPLES_BASE/node_modules/tsx/dist/cli.mjs" ]; then
         # Run principles checker and store results.
         #