@boyingliu01/xp-gate 0.20.1 → 0.21.0

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/python.sh

@@ -9,10 +9,26 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
 source "$SCRIPT_DIR/../adapter-common.sh" 2>/dev/null || true
 
-run_static_analysis() {
-  require_tool mypy "mypy" || return 1
+# A mypy target must exist AND actually contain .py files: a bare directory
+# check lets through TS repos' src/ (mypy exits 2 with "There are no .py[i]
+# files in directory" — #513 R1 expert-B reproduction), and a file check
+# alone would accept empty shell directories. Supports files too, so a
+# scope declaration may name a single .py file.
+_mypy_target_usable() {
+  [ -e "$1" ] || return 1
+  [ -n "$(find "$1" -name '*.py' -print 2>/dev/null | grep .)" ]
+}
 
-  # 口径 = CI type job（.github/workflows/ci.yml:43-45）的两条命令，逐字一致。
+run_static_analysis() {
+  # NOTE: require_tool mypy runs AFTER target resolution, not here (#513 R2
+  # expert-C): a repo with no type surface AND no mypy installed must reach
+  # the SKIP branch (nothing to check) instead of false-BLOCKing on the
+  # missing tool. The tool is only required when there is something to check.
+
+  # 口径 = CI type job（.github/workflows/ci.yml:43-45）的目录集合（src/、
+  # scripts/），并按调用方式对齐：**逐目录单独调用**（#513 R1 专家 B 实测：
+  # 合并为 `mypy src scripts` 一次跑，src/util.py 与 scripts/util.py 同名时
+  # 报 "Duplicate module named" exit 2，而 CI 分开跑各自 exit 0）。
   # 为什么不能写 `mypy .`：`.` 会递归扫到两类文件，而它们在仓库里从未被声明为
   # 门禁面，CI 也从不检查：
   #   ① 根目录一次性调研/演示脚本（fetch_*.py、demo_*.py、validate_*.py 等）——
@@ -28,10 +44,61 @@ run_static_analysis() {
   # 口径一致性由仓库侧 BATS 测试双向锁住：
   # githooks/__tests__/adapter-mypy-pester-scope.test.bats（含"适配器里不得再
   # 出现裸 mypy ."），防止 `mypy .` 被写回来时无人报警。
+  #
+  # #513：上述 `src/`+`scripts/` 是"单一仓库的 CI 声明面"，不能当成所有 Python
+  # 仓库的布局硬编码——无 src/ 的仓库（如 skill-cert 的 engine/ 布局）会得到
+  # `mypy: can't read file 'src'` 而对任何 .py 提交恒 BLOCK，违反本项目
+  # "门禁无法运行 → SKIP 而非 BLOCK" 规范。口径回归"按仓库声明"三级解析：
+  #   ① 仓库根 `.xp-gate-mypy-scope`（每行一个目录；支持整行或行内 # 注释）
+  #      存在则为其权威声明，声明条目同样过 usable 守卫（缺失/无 .py → WARN 跳过）；
+  #   ② 否则仅对 usable 的默认目录（src/、scripts/）执行；
+  #   ③ 两者皆无（或声明为空）→ 打印提示并 exit 0，绝不把 mypy 空跑一次。
   echo "Running Python static analysis (mypy)..."
-  mypy src/ || return 1
-  mypy scripts/
-  return $?
+  local -a MYPY_TARGETS=()
+  local _mypy_declared=0
+  if [ -f .xp-gate-mypy-scope ]; then
+    while IFS= read -r line || [ -n "$line" ]; do
+      line="${line%%#*}"
+      line="${line#"${line%%[![:space:]]*}"}"
+      line="${line%"${line##*[![:space:]]}"}"
+      [ -z "$line" ] && continue
+      _mypy_declared=1
+      if _mypy_target_usable "$line"; then
+        MYPY_TARGETS+=("$line")
+      else
+        echo "  ⚠ mypy scope: declared target '$line' does not exist or contains no .py files — skipped"
+      fi
+    done < .xp-gate-mypy-scope
+    echo "  scope: .xp-gate-mypy-scope declaration"
+    if [ "${#MYPY_TARGETS[@]}" -eq 0 ]; then
+      if [ "$_mypy_declared" -eq 1 ]; then
+        echo "  ⚠ mypy: .xp-gate-mypy-scope has no usable target (all missing or without .py files) — skipping"
+      else
+        echo "  ⚠ mypy: .xp-gate-mypy-scope is present but empty (comments/blank lines only) — skipping"
+      fi
+      return 0
+    fi
+  else
+    if [ -d src ] && _mypy_target_usable src; then
+      MYPY_TARGETS+=(src)
+    fi
+    if [ -d scripts ] && _mypy_target_usable scripts; then
+      MYPY_TARGETS+=(scripts)
+    fi
+    if [ "${#MYPY_TARGETS[@]}" -eq 0 ]; then
+      echo "  ℹ️  mypy: repo declares no type surface (no .xp-gate-mypy-scope; src/ scripts/ absent or without .py files) — skipping"
+      echo "      if this repo does have a type surface, declare it: create .xp-gate-mypy-scope (one directory per line)"
+      return 0
+    fi
+  fi
+  # 逐目标调用并聚合退出码（口径见函数头注释）。
+  require_tool mypy "mypy" || return 1
+  local _mypy_rc=0
+  local _mypy_t
+  for _mypy_t in "${MYPY_TARGETS[@]}"; do
+    mypy "$_mypy_t" || _mypy_rc=1
+  done
+  return $_mypy_rc
 }
 
 run_lint() {