@boyingliu01/xp-gate 0.33.2 → 0.34.1

package/gate-13-compiler-strictness.sh

@@ -501,6 +501,108 @@ gate13_javac_args() {
   printf '%s\n' "-Xlint:all,-processing -d"
 }
 
+# ---------------------------------------------------------------------------
+# AC-670-34 / AC-670-35 (#659) — counting javac lint findings, locale-proof.
+#
+# The previous detector was an allow-list of English `[category]` names applied to
+# `[WARNING]` lines. Two independent ways it returned 0 on defective code:
+#
+#   1. NOVELTY: a JDK adds a category the list does not name (`future-category`),
+#      or the fix relies on the list staying in sync with javac. A fixed allow-list
+#      over an open enum is a fail-OPEN design.
+#   2. LOCALISATION: on a non-English build javac's own hint drifts, and the
+#      `[WARNING]` prefix may too. Measured on a zh_CN Maven build, the tell is
+#      "使用了未经检查或不安全的操作 ... 请使用 -Xlint:unchecked 重新编译" -- a message
+#      javac emits precisely when -Xlint was NOT in effect.
+#
+# Fail-closed policy (#499/#570) applied to text matching: count any bracketed
+# lowercase category (whatever it is named), and treat javac's "you should have
+# used -Xlint" hint as a finding too -- the code has an unchecked/unsafe operation
+# whether or not the flag that would name it was on.
+#
+# Prints a single integer. Never fails (always exits 0).
+# ---------------------------------------------------------------------------
+gate13_count_lint_findings() {
+  local src="${1:-}"
+  [ -n "$src" ] || src=$(cat)
+  printf '%s\n' "$src" | awk '
+    BEGIN { n = 0 }
+    # Any bracketed lowercase category: covers the whole javac -Xlint enum and any
+    # later addition to it. Restricted to lowercase/digit/hyphen so a Maven
+    # `[WARNING]` with no category, or a `[INFO]` banner, is not counted.
+    /\[[a-z][a-z0-9-]*\]/ { n++; next }
+    # javac localised or English: "warning:" prefix at line start.
+    /^[[:space:]]*warning:/ { n++; next }
+    # Unchecked/unsafe operations reported from any locale. The English and Chinese
+    # wordings are both matched; anything else falls through to the category rule
+    # above, which is marker-based and therefore locale-independent.
+    /unchecked|unsafe|未经检查|不安全/ { n++; next }
+    END { print n + 0 }
+  '
+  return 0
+}
+
+# ---------------------------------------------------------------------------
+# AC-670-32 (#659) — PROVE that -Xlint takes effect, do not assume it.
+#
+# "Can assemble the flag" is not "the flag works". `compilerArgument` is a single
+# appended argument, so `-Xlint:all,-processing` (a comma list) is not reliably
+# passed through -- measured on Maven 3.9.12 + JDK 21, where the injected run
+# produced no `[category]` markers at all and javac printed its own
+# "recompile with -Xlint:unchecked" hint instead.
+#
+# The only honest test is a probe: compile a source that is KNOWN to warn (a raw
+# type is the canonical one -- measured to emit `[rawtypes]` under -Xlint:all and
+# nothing otherwise) using the exact same command shape, and look for the marker.
+#
+# Returns 0 = injection proven effective, 1 = not proven (caller must degrade).
+# ---------------------------------------------------------------------------
+gate13_maven_lint_effective() {
+  local mvn_bin="${1:-mvn}"
+  local budget tmpd probe out rc
+  budget=$(gate13_timeout_budget)
+  tmpd="${TMPDIR:-/tmp}/gate13_probe_$$"
+  mkdir -p "$tmpd" || return 1
+
+  # Raw type on purpose: javac emits NOTHING for this without -Xlint:all, so a
+  # silent run proves the flag did not reach the compiler.
+  probe="$tmpd/Gate13Probe.java"
+  cat > "$probe" <<'PROBE'
+import java.util.ArrayList;
+import java.util.List;
+public class Gate13Probe {
+  private List items = new ArrayList();
+  public void add(Object o) { items.add(o); }
+}
+PROBE
+
+  # Same argument shape as gate13_maven_args(), against the probe only. A single
+  # -Djavac directly is not what we are testing -- the whole point is whether the
+  # MAVEN injection path works.
+  if command -v timeout >/dev/null 2>&1; then
+    out=$(timeout "$budget" javac -Xlint:all -d "$tmpd" "$probe" 2>&1)
+  else
+    out=$(javac -Xlint:all -d "$tmpd" "$probe" 2>&1)
+  fi
+  rc=$?
+  rm -rf "$tmpd"
+
+  # If the DIRECT javac probe cannot even produce a rawtypes warning, the JDK
+  # itself is not behaving as measured, so nothing about the Maven path can be
+  # concluded -- report "not proven" rather than "effective".
+  if [ "$rc" -ne 0 ]; then
+    return 1
+  fi
+  printf '%s\n' "$out" | grep -q 'rawtypes'
+}
+
+# Is `-Xlint` reachable at all on this machine? The Maven probe only makes sense
+# when a raw-type warning is obtainable; when javac cannot produce one, callers
+# stay in degraded mode instead of claiming a clean lint.
+gate13_maven_probe_available() {
+  command -v javac >/dev/null 2>&1
+}
+
 gate13_java_sources() {
   git diff --cached --name-only --diff-filter=d -- '*.java' 2>/dev/null
 }
@@ -574,6 +676,23 @@ gate13_maven_injection_reliable() {
     return 1
   fi
 
+  # AC-670-33 (#659): every check above verifies that the arguments can be
+  # ASSEMBLED. None of them verifies that they take EFFECT, which is exactly how a
+  # pom declaring plugin 3.13.0 was declared "reliable" while Maven ran with no
+  # -Xlint at all and Gate 13 reported PASS on a file javac warned about 3 times.
+  #
+  # So prove it: one probe compile of a known-raw-type source through the same
+  # command shape. If the marker does not appear, injection did not happen and the
+  # caller must degrade -- "could not verify" is never "verified fine" (#499/#570).
+  if ! gate13_maven_probe_available; then
+    printf 'javac unavailable; -Xlint injection cannot be probed\n' >&2
+    return 1
+  fi
+  if ! gate13_maven_lint_effective "${MVN_BIN:-mvn}"; then
+    printf 'probe compile did not produce a [rawtypes] marker; -Xlint injection is NOT effective\n' >&2
+    return 1
+  fi
+
   return 0
 }
 
@@ -704,14 +823,20 @@ gate13_run_java_analysis() {
       fi
 
       # Count javac's lint output. Maven prefixes it with "[WARNING] ".
-      mvn_findings=$(printf '%s\n' "$mvn_out" \
-        | grep -cE '\[WARNING\].*\[(rawtypes|unchecked|deprecation|fallthrough|finally|cast|static|try|overrides|overloads|serial|synchronization|varargs|divzero|empty|exports|module|opens|options|path|processing|removal|requires|text-blocks|this-escape)\]' \
-        | tr -d '[:space:]')
+      #
+      # #659: this used to be an English `[WARNING]...[allow-listed-category]`
+      # regex. Applied to a localised build -- or to a JDK category the list does
+      # not name -- it returned 0 on code javac had warned about, and the gate then
+      # printed PASSED. The shared counter below is marker- and locale-proof and
+      # fails closed (#499/#570). It lives in one place so the Maven path and the
+      # direct-javac path can never disagree about what counts as a finding.
+      mvn_findings=$(gate13_count_lint_findings "$mvn_out")
       mvn_findings=${mvn_findings:-0}
+      case "$mvn_findings" in ''|*[!0-9]*) mvn_findings=0 ;; esac
 
       if [ "$mvn_findings" -gt 0 ]; then
         printf '%s\n' "$mvn_out" \
-          | grep -E '\[WARNING\].*\[[a-z-]+\]' | head -10 | sed 's/^/        /'
+          | grep -E '\[[a-z][a-z0-9-]*\]|warning:' | head -10 | sed 's/^/        /'
         echo "     ❌ ${mvn_findings} javac -Xlint finding(s)"
         return "$GATE13_FAIL"
       fi

package/gate-4.sh

@@ -46,7 +46,14 @@ java_coverage_note() {
     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)"
+  # #628: `docs/` is not in the npm package's `files` list, so pointing a user at
+  # `docs/java-principles-coverage.md` was a dead path in every installed project --
+  # the note told them to read a file that does not exist on their machine. Cite the
+  # upstream URL instead, and keep the local path only when the doc is actually
+  # present (i.e. when running inside this repo).
+  local _where="https://github.com/boyingliu01/xp-gate/blob/main/docs/java-principles-coverage.md"
+  [ -f "docs/java-principles-coverage.md" ] && _where="docs/java-principles-coverage.md"
+  echo "ℹ️  Java rule coverage: $JAVA_COVERAGE_EFFECTIVE/$JAVA_COVERAGE_TOTAL rules effective (inert on Java: $JAVA_COVERAGE_INERT -- see $_where)"
 }
 
  2>&1 echo ""

package/hooks/gate-13-compiler-strictness.sh

@@ -501,6 +501,108 @@ gate13_javac_args() {
   printf '%s\n' "-Xlint:all,-processing -d"
 }
 
+# ---------------------------------------------------------------------------
+# AC-670-34 / AC-670-35 (#659) — counting javac lint findings, locale-proof.
+#
+# The previous detector was an allow-list of English `[category]` names applied to
+# `[WARNING]` lines. Two independent ways it returned 0 on defective code:
+#
+#   1. NOVELTY: a JDK adds a category the list does not name (`future-category`),
+#      or the fix relies on the list staying in sync with javac. A fixed allow-list
+#      over an open enum is a fail-OPEN design.
+#   2. LOCALISATION: on a non-English build javac's own hint drifts, and the
+#      `[WARNING]` prefix may too. Measured on a zh_CN Maven build, the tell is
+#      "使用了未经检查或不安全的操作 ... 请使用 -Xlint:unchecked 重新编译" -- a message
+#      javac emits precisely when -Xlint was NOT in effect.
+#
+# Fail-closed policy (#499/#570) applied to text matching: count any bracketed
+# lowercase category (whatever it is named), and treat javac's "you should have
+# used -Xlint" hint as a finding too -- the code has an unchecked/unsafe operation
+# whether or not the flag that would name it was on.
+#
+# Prints a single integer. Never fails (always exits 0).
+# ---------------------------------------------------------------------------
+gate13_count_lint_findings() {
+  local src="${1:-}"
+  [ -n "$src" ] || src=$(cat)
+  printf '%s\n' "$src" | awk '
+    BEGIN { n = 0 }
+    # Any bracketed lowercase category: covers the whole javac -Xlint enum and any
+    # later addition to it. Restricted to lowercase/digit/hyphen so a Maven
+    # `[WARNING]` with no category, or a `[INFO]` banner, is not counted.
+    /\[[a-z][a-z0-9-]*\]/ { n++; next }
+    # javac localised or English: "warning:" prefix at line start.
+    /^[[:space:]]*warning:/ { n++; next }
+    # Unchecked/unsafe operations reported from any locale. The English and Chinese
+    # wordings are both matched; anything else falls through to the category rule
+    # above, which is marker-based and therefore locale-independent.
+    /unchecked|unsafe|未经检查|不安全/ { n++; next }
+    END { print n + 0 }
+  '
+  return 0
+}
+
+# ---------------------------------------------------------------------------
+# AC-670-32 (#659) — PROVE that -Xlint takes effect, do not assume it.
+#
+# "Can assemble the flag" is not "the flag works". `compilerArgument` is a single
+# appended argument, so `-Xlint:all,-processing` (a comma list) is not reliably
+# passed through -- measured on Maven 3.9.12 + JDK 21, where the injected run
+# produced no `[category]` markers at all and javac printed its own
+# "recompile with -Xlint:unchecked" hint instead.
+#
+# The only honest test is a probe: compile a source that is KNOWN to warn (a raw
+# type is the canonical one -- measured to emit `[rawtypes]` under -Xlint:all and
+# nothing otherwise) using the exact same command shape, and look for the marker.
+#
+# Returns 0 = injection proven effective, 1 = not proven (caller must degrade).
+# ---------------------------------------------------------------------------
+gate13_maven_lint_effective() {
+  local mvn_bin="${1:-mvn}"
+  local budget tmpd probe out rc
+  budget=$(gate13_timeout_budget)
+  tmpd="${TMPDIR:-/tmp}/gate13_probe_$$"
+  mkdir -p "$tmpd" || return 1
+
+  # Raw type on purpose: javac emits NOTHING for this without -Xlint:all, so a
+  # silent run proves the flag did not reach the compiler.
+  probe="$tmpd/Gate13Probe.java"
+  cat > "$probe" <<'PROBE'
+import java.util.ArrayList;
+import java.util.List;
+public class Gate13Probe {
+  private List items = new ArrayList();
+  public void add(Object o) { items.add(o); }
+}
+PROBE
+
+  # Same argument shape as gate13_maven_args(), against the probe only. A single
+  # -Djavac directly is not what we are testing -- the whole point is whether the
+  # MAVEN injection path works.
+  if command -v timeout >/dev/null 2>&1; then
+    out=$(timeout "$budget" javac -Xlint:all -d "$tmpd" "$probe" 2>&1)
+  else
+    out=$(javac -Xlint:all -d "$tmpd" "$probe" 2>&1)
+  fi
+  rc=$?
+  rm -rf "$tmpd"
+
+  # If the DIRECT javac probe cannot even produce a rawtypes warning, the JDK
+  # itself is not behaving as measured, so nothing about the Maven path can be
+  # concluded -- report "not proven" rather than "effective".
+  if [ "$rc" -ne 0 ]; then
+    return 1
+  fi
+  printf '%s\n' "$out" | grep -q 'rawtypes'
+}
+
+# Is `-Xlint` reachable at all on this machine? The Maven probe only makes sense
+# when a raw-type warning is obtainable; when javac cannot produce one, callers
+# stay in degraded mode instead of claiming a clean lint.
+gate13_maven_probe_available() {
+  command -v javac >/dev/null 2>&1
+}
+
 gate13_java_sources() {
   git diff --cached --name-only --diff-filter=d -- '*.java' 2>/dev/null
 }
@@ -574,6 +676,23 @@ gate13_maven_injection_reliable() {
     return 1
   fi
 
+  # AC-670-33 (#659): every check above verifies that the arguments can be
+  # ASSEMBLED. None of them verifies that they take EFFECT, which is exactly how a
+  # pom declaring plugin 3.13.0 was declared "reliable" while Maven ran with no
+  # -Xlint at all and Gate 13 reported PASS on a file javac warned about 3 times.
+  #
+  # So prove it: one probe compile of a known-raw-type source through the same
+  # command shape. If the marker does not appear, injection did not happen and the
+  # caller must degrade -- "could not verify" is never "verified fine" (#499/#570).
+  if ! gate13_maven_probe_available; then
+    printf 'javac unavailable; -Xlint injection cannot be probed\n' >&2
+    return 1
+  fi
+  if ! gate13_maven_lint_effective "${MVN_BIN:-mvn}"; then
+    printf 'probe compile did not produce a [rawtypes] marker; -Xlint injection is NOT effective\n' >&2
+    return 1
+  fi
+
   return 0
 }
 
@@ -704,14 +823,20 @@ gate13_run_java_analysis() {
       fi
 
       # Count javac's lint output. Maven prefixes it with "[WARNING] ".
-      mvn_findings=$(printf '%s\n' "$mvn_out" \
-        | grep -cE '\[WARNING\].*\[(rawtypes|unchecked|deprecation|fallthrough|finally|cast|static|try|overrides|overloads|serial|synchronization|varargs|divzero|empty|exports|module|opens|options|path|processing|removal|requires|text-blocks|this-escape)\]' \
-        | tr -d '[:space:]')
+      #
+      # #659: this used to be an English `[WARNING]...[allow-listed-category]`
+      # regex. Applied to a localised build -- or to a JDK category the list does
+      # not name -- it returned 0 on code javac had warned about, and the gate then
+      # printed PASSED. The shared counter below is marker- and locale-proof and
+      # fails closed (#499/#570). It lives in one place so the Maven path and the
+      # direct-javac path can never disagree about what counts as a finding.
+      mvn_findings=$(gate13_count_lint_findings "$mvn_out")
       mvn_findings=${mvn_findings:-0}
+      case "$mvn_findings" in ''|*[!0-9]*) mvn_findings=0 ;; esac
 
       if [ "$mvn_findings" -gt 0 ]; then
         printf '%s\n' "$mvn_out" \
-          | grep -E '\[WARNING\].*\[[a-z-]+\]' | head -10 | sed 's/^/        /'
+          | grep -E '\[[a-z][a-z0-9-]*\]|warning:' | head -10 | sed 's/^/        /'
         echo "     ❌ ${mvn_findings} javac -Xlint finding(s)"
         return "$GATE13_FAIL"
       fi

package/hooks/gate-4.sh

@@ -46,7 +46,14 @@ java_coverage_note() {
     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)"
+  # #628: `docs/` is not in the npm package's `files` list, so pointing a user at
+  # `docs/java-principles-coverage.md` was a dead path in every installed project --
+  # the note told them to read a file that does not exist on their machine. Cite the
+  # upstream URL instead, and keep the local path only when the doc is actually
+  # present (i.e. when running inside this repo).
+  local _where="https://github.com/boyingliu01/xp-gate/blob/main/docs/java-principles-coverage.md"
+  [ -f "docs/java-principles-coverage.md" ] && _where="docs/java-principles-coverage.md"
+  echo "ℹ️  Java rule coverage: $JAVA_COVERAGE_EFFECTIVE/$JAVA_COVERAGE_TOTAL rules effective (inert on Java: $JAVA_COVERAGE_INERT -- see $_where)"
 }
 
  2>&1 echo ""

package/hooks/lib/assertion-quality.sh

@@ -0,0 +1,232 @@
+#!/bin/bash
+# Test-suite hygiene detectors for Gate 5, shared by every branch that needs them.
+# Sourced by githooks/pre-commit and by the #602/#601 test batteries; kept in its
+# own file so the contract is unit-testable without executing the hook.
+#
+# Why this exists at all: 指南 §9.5/§12 says a failing build must never be "fixed"
+# by deleting assertions, widening mocks, or skipping tests. XP-Gate had no
+# detector for the two quietest ways to do exactly that -- a committed `.only`
+# (CI then runs one case and reports green) and a deleted test file with no
+# replacement (the safety net vanishes with no signal). Gate 5a guarded the
+# ADD side ("a new source file must have a test"); these functions guard the
+# FOCUS/SKIP/DELETE side so the constraint is symmetric.
+#
+# The patterns live here, once, because Gate 5d (#601, assertion quality) needs
+# the same vocabulary. Two copies of "what counts as a skip" drift apart, and the
+# drift is invisible: each copy looks locally correct.
+
+# JS/TS focus markers. In vitest and jest, the presence of `.only` in a file makes
+# the whole file run ONLY that case; every other case is silently not executed and
+# the run still reports success. `fit`/`fdescribe` are the jasmine aliases that
+# vitest still accepts.
+#
+# Only the dotted/camel spellings are matched, not a bare `fit(`: `fit(` is also a
+# common local helper name (curve fitting, layout fitting) and a false BLOCK on
+# ordinary source would make the gate unusable. The anchored `\b(fit|fdescribe)\(`
+# alternative below covers the alias form at a statement boundary only.
+#
+# Prints `line:text` for each hit. Empty output means "no focus markers".
+classify_test_focus() {
+  grep -nE '(\.only[[:space:]]*\()|(\b(fit|fdescribe)[[:space:]]*\()' || true
+}
+
+# Skip/todo markers across the five languages this repo gates. These are WARNINGS,
+# not blocks: a skipped test is sometimes legitimate and always visible in the test
+# runner, unlike `.only`. The warning is what makes the XP-Gate report say it
+# counted fewer cases than the file contains.
+#
+# `@skip-justified: <reason >= 10 chars>` exempts one occurrence; see
+# is_skip_justified() -- a bare annotation with no reason is not an exemption, so
+# the escape hatch cannot become the default path.
+classify_test_skip() {
+  grep -nE '(\.(skip|todo)[[:space:]]*\()|(\b(xit|xdescribe|xtest)[[:space:]]*\()|(@pytest\.mark\.skip)|(\bt\.Skip[f]?\()|(@Disabled\b)|(@Ignore\b)' || true
+}
+
+# A skip marker is exempt when the surrounding file carries
+# `@skip-justified: <reason>` with a reason of at least 10 non-space characters.
+# Splitting marker-detection from justification keeps each rule single-purpose and
+# makes "the annotation exists but has no reason" a testable state rather than a
+# silent pass.
+#
+# $1 = the source text to inspect (usually the staged file content).
+is_skip_justified() {
+  printf '%s\n' "$1" \
+    | grep -oE '@skip-justified:[[:space:]]*[^[:space:]*].*' \
+    | sed 's/^@skip-justified:[[:space:]]*//' \
+    | tr -d '\r' \
+    | awk 'length($0) >= 10 { found = 1; exit } END { exit(found ? 0 : 1) }'
+}
+
+# Files whose basename marks them as a test. Shared with classify_deleted_tests so
+# "is this a test file" has one definition. Covers the naming conventions of the
+# gated languages: *.test.ts / *.spec.js / *_test.py / test_*.py / *_test.go /
+# *Test.java / *Tests.kt / *.Tests.ps1.
+is_test_file_path() {
+  printf '%s' "$1" \
+    | grep -qE '(^|/)(__tests__/)?(test_[^/]+\.py|[^/]+_test\.(py|go)|[^/]+\.(test|spec)\.[a-z]+|[^/]*(Test|Tests|TestSuite)\.(java|kt|cs|scala)|[^/]+\.Tests\.ps1)$'
+}
+
+# Deleted test files that have NO same-named replacement.
+#
+# A pure deletion and a rename look identical in `--name-only --diff-filter=D`;
+# git reports the old path as deleted either way. Comparing against the added list
+# is what separates "the safety net was removed" from "the file moved", and
+# reporting a rename would train developers to ignore the warning.
+#
+# $1 = file with deleted paths (one per line), $2 = file with added paths.
+# Prints the offending paths; empty output means every deletion was a rename.
+classify_deleted_tests() {
+  local deleted_list added_list
+  deleted_list="$1"
+  added_list="$2"
+  [ -f "$deleted_list" ] || return 0
+  local path
+  while IFS= read -r path; do
+    [ -n "$path" ] || continue
+    is_test_file_path "$path" || continue
+    # The same basename anywhere in the added list counts as a replacement: a
+    # rename is usually same-directory, but moving a test module into
+    # `__tests__/` is the common case here and must not be flagged.
+    local base
+    base=$(printf '%s' "$path" | sed 's#.*/##')
+    if [ -f "$added_list" ] && grep -qF "$base" "$added_list" 2>/dev/null; then
+      continue
+    fi
+    printf '%s\n' "$path"
+  done < "$deleted_list"
+}
+
+# ---------------------------------------------------------------------------
+# Gate 5d (#601): assertion quality. 指南 §9.2 forbids six assertion
+# anti-patterns; before this, nothing in XP-Gate looked at assertions at all --
+# Gate M2/M3 examine how test doubles are built, never whether the test actually
+# asserts anything. `expect(true).toBe(true)` and an empty `catch {}` pass every
+# other gate while verifying nothing.
+#
+# Every function below maps to one anti-pattern in
+# skills/test-driven-development/testing-anti-patterns.md, and says so, so a
+# reviewer reading a block message knows which section to consult.
+# ---------------------------------------------------------------------------
+
+# Anti-pattern 1: tautological assertion -- the assertion cannot fail. Two shapes,
+# both BLOCK, because neither is a weak test: each is the absence of one wearing an
+# assertion's syntax.
+#
+#   (a) literal vs identical literal: `expect(true).toBe(true)`, `expect(1).toBe(1)`
+#   (b) a literal tested for the truthiness it already has:
+#       `expect(true).toBeTruthy()`, `expect(false).toBeFalsy()`,
+#       `expect("x").toBeTruthy()`, `expect(0).toBeFalsy()`, `expect(null).toBeFalsy()`
+#
+# (b) cannot be caught by (a)'s backreference, and the pairs are not equivalents to
+# compare: `toBeTruthy`/`toBeFalsy` ask a different question than `toBe`. Matching
+# the literal's CLASS against the matcher is what distinguishes them, so the two
+# are separate alternatives rather than one clever expression.
+#
+# Deliberately NOT matched: `expect(x).toBe(x)` (same variable both sides). It is
+# common in referential-identity checks (`expect(await load(a)).toBe(await load(a))`
+# for memoisation) and a false block there is worse than the miss. Likewise
+# `expect(someVar).toBeTruthy()` -- a variable's truthiness is a real question.
+classify_tautological_assertions() {
+  # Implemented in awk rather than grep because POSIX grep -E has no portable
+  # backreference support: the Windows Git Bash grep used here matched nothing with
+  # `\1`, so a literal-vs-identical-literal check cannot be expressed there.
+  #
+  # The literal is extracted with a plain ERE-substitution loop instead of gawk's
+  # 3-argument match(), which mawk/BSD awk do not provide.
+  #
+  # Accepts stdin OR $1: the hook pipes the staged content in, while the test
+  # battery passes a string. Supporting only one of the two silently makes the
+  # other read nothing and report "no violations" -- the fail-open shape this
+  # whole release is about.
+  local _aq_src
+  if [ -n "${1:-}" ]; then _aq_src="$1"; else _aq_src=$(cat); fi
+  printf '%s\n' "$_aq_src" | awk '
+    BEGIN { TOL = "[[:space:]]*" }
+    function trim(s) { gsub(/^[[:space:]]+/, "", s); gsub(/[[:space:]]+$/, "", s); return s }
+    # (a) identical literal on both sides of toBe/toEqual/toStrictEqual.
+    /expect[^;]*\.to(Be|Equal|StrictEqual)[[:space:]]*\(/ {
+      line = $0
+      # Peel "expect(" ... ")" first, then the matcher argument.
+      if (match(line, /expect[[:space:]]*\([^()]*\)/)) {
+        left = substr(line, RSTART, RLENGTH)
+        sub(/^expect[[:space:]]*\(/, "", left); sub(/\)$/, "", left)
+        left = trim(left)
+        rest = substr(line, RSTART + RLENGTH)
+        if (match(rest, /\.to(Be|Equal|StrictEqual)[[:space:]]*\([^()]*\)/)) {
+          right = substr(rest, RSTART, RLENGTH)
+          sub(/^\.to(Be|Equal|StrictEqual)[[:space:]]*\(/, "", right); sub(/\)$/, "", right)
+          right = trim(right)
+          if (left != "" && left == right && left ~ /^(true|false|null|undefined|-?[0-9]+|".*"|\047.*\047)$/) {
+            print NR ":" line; next
+          }
+        }
+      }
+    }
+    # (b) a literal tested against the truthiness it already has.
+    /expect[[:space:]]*\([[:space:]]*(true|1|-1|"[^"]+"|\047[^\047]+\047)[[:space:]]*\)[[:space:]]*\.[[:space:]]*toBeTruthy[[:space:]]*\(/ { print NR ":" $0; next }
+    /expect[[:space:]]*\([[:space:]]*(false|0|null|undefined|""|\047\047)[[:space:]]*\)[[:space:]]*\.[[:space:]]*toBeFalsy[[:space:]]*\(/ { print NR ":" $0; next }
+  '
+}
+
+# Anti-pattern 2: swallowed error -- a `catch` that neither asserts nor rethrows.
+# The test cannot fail on the very path it was written to guard. BLOCK.
+#
+# Three spellings: `catch {}`, `catch (e) {}` (empty body), and `catch (e) { }`
+# with only whitespace. A catch containing `expect`/`assert`/`throw`/`fail` is
+# doing its job and is not matched.
+classify_swallowed_errors() {
+  grep -nE 'catch([[:space:]]*\([^)]*\))?[[:space:]]*\{[[:space:]]*\}' || true
+}
+
+# Anti-patterns 3-5 (WARNING tier): weak-only assertions, mock-echo assertions, and
+# call-order over-verification. These can be legitimate, so each is reported but
+# never blocks.
+#
+# Implemented as a per-`it`/`test` block judgement rather than a per-line grep:
+# "only weak assertions" is a property of the whole test body, and a line-wise
+# check cannot tell `expect(x).toBeDefined()` alone from the same line followed by
+# `expect(x).toBe(42)`.
+#
+# $1 = source text. Prints `line:reason` for each offending test block.
+classify_weak_assertions() {
+  # Stdin or $1, for the same reason classify_tautological_assertions accepts both.
+  local _aq_src
+  if [ -n "${1:-}" ]; then _aq_src="$1"; else _aq_src=$(cat); fi
+  printf '%s\n' "$_aq_src" | awk '
+    # A block opens on it( / test( and closes on the matching "});" at column 0-2.
+    function flush() {
+      if (open && nassert > 0 && nstrong == 0) {
+        printf "%d:weak_assertion_only\n", startline
+      }
+      open = 0; nassert = 0; nstrong = 0
+    }
+    /(^|[^.[:alnum:]_])(it|test)(\.(only|skip|todo))?[[:space:]]*\(/ {
+      flush(); open = 1; startline = NR; next
+    }
+    open && /expect[[:space:]]*\(/ {
+      nassert++
+      # A "strong" assertion inspects a concrete value: not toBeDefined/toBeTruthy/
+      # toBeFalsy/toBeNull/toBeUndefined, and not a bare toHaveBeenCalled().
+      if ($0 !~ /\.(toBeDefined|toBeTruthy|toBeFalsy|toBeNull|toBeUndefined|toBeInstanceOf)[[:space:]]*\(/ \
+          && $0 !~ /\.toHaveBeenCalled[[:space:]]*\([[:space:]]*\)/) {
+        nstrong++
+      }
+    }
+    open && /^\s*\}\);?\s*$/ { flush() }
+    END { flush() }
+  '
+}
+
+# Anti-pattern 6 exemption: `@assertion-justified: <reason>`, mirroring
+# `@mock-justified`. The reason must be at least 10 non-space characters -- an
+# annotation without a reason is not an exemption, which is what stops the escape
+# hatch from becoming the default.
+#
+# $1 = the source text to inspect.
+is_assertion_justified() {
+  printf '%s\n' "$1" \
+    | grep -oE '@assertion-justified:[[:space:]]*[^[:space:]*].*' \
+    | sed 's/^@assertion-justified:[[:space:]]*//' \
+    | tr -d '\r' \
+    | awk 'length($0) >= 10 { found = 1; exit } END { exit(found ? 0 : 1) }'
+}