@boyingliu01/xp-gate 0.31.1 → 0.31.2

package/hooks/lib/gate-5c-alignment.sh

@@ -0,0 +1,145 @@
+#!/bin/bash
+# Gate 5c: spec/test alignment (#585).
+#
+# Extracted from pre-commit so the contract is unit-testable without executing the
+# hook, the same way lib/coverage-total.sh and lib/sprint-gate-report.sh are.
+#
+# The defect this file exists for: the whole check sat inside
+#     if [ -f "$REQ_IDS_FILE" ] && command -v jq >/dev/null 2>&1; then
+# so in the normal state — req-ids.json is produced by `xp-gate check-alignment`
+# into .sprint-state/, which is gitignored and therefore absent in every fresh
+# clone — the gate printed NOTHING. Not PASS, not FAIL, not SKIP. The quality
+# report had no slot for it either. A repository's semantic alignment had never
+# been checked once and every report was green.
+#
+# A gate that answers "not checked" by staying silent is the same defect class as
+# #449, #499, #570, #575 and #594: silence read as success.
+
+# Test-file conventions, per language. A gate that only knows JS/TS reports
+# "0 annotated, 0 uncovered" on a PowerShell, Python, Go, Java or Kotlin
+# repository — a vacuous green (#585).
+#
+# Pester:  *.Tests.ps1, *.test.ps1 (Pester's documented naming)
+# pytest:  test_*.py, *_test.py
+# Go:      *_test.go
+# Java:    *Test.java, *Tests.java
+# Kotlin:  *Test.kt, *Tests.kt
+# JS/TS:   *.test.*, *.spec.*
+GATE5C_TEST_FILE_PATTERN='(\.(test|spec)\.(ts|tsx|js|jsx|cjs|mjs)$)|(\.([Tt]ests?)\.ps1$)|(^(test_|.*/test_)[^/]*\.py$)|(^([^/]*_test)\.py$)|(_test\.go$)|([Tt]ests?\.java$)|([Tt]ests?\.kt$)'
+
+# Is this changed-file list carrying anything that looks like a test file?
+#
+# Uses the same CHANGED_FILES variable the hook holds at that point in its flow.
+gate_5c_test_files() {
+  printf '%s\n' "${CHANGED_FILES:-}" \
+    | grep -E "$GATE5C_TEST_FILE_PATTERN" 2>/dev/null || true
+}
+
+# One-line-per-id extraction. Reads req-ids.json when jq is available and falls
+# back to grep when it is not: `jq` missing used to disable the gate silently, and
+# a JSON array of strings is simple enough to read without it.
+gate_5c_req_ids() {
+  local file="$1"
+  if [ ! -f "$file" ]; then
+    return 0
+  fi
+  if command -v jq >/dev/null 2>&1; then
+    jq -r '.[]' "$file" 2>/dev/null && return 0
+  fi
+  # Fallback: quoted strings inside the array. Good enough for a flat id list, and
+  # it fails toward EMPTY rather than toward a bogus id.
+  grep -oE '"[^"]+"' "$file" 2>/dev/null | tr -d '"' || true
+}
+
+# The @test REQ-XXX annotations inside one file.
+gate_5c_annotations() {
+  local file="$1"
+  grep -oE '@test[[:space:]]+REQ-[A-Za-z0-9-]+' "$file" 2>/dev/null \
+    | sed 's/@test[[:space:]]*//' | sort -u || true
+}
+
+# Gate 5c entry point. Echoes the verdict; returns 1 to BLOCK.
+#
+# Reads CHANGED_FILES (set by pre-commit). Writes GATE_5C_STATUS for the report:
+# PASS, SKIP or BLOCK — never empty, because "empty" is what was broken.
+gate_5c_alignment() {
+  local req_ids_file=".sprint-state/phase-outputs/req-ids.json"
+  GATE_5C_STATUS=""
+
+  if [ ! -f "$req_ids_file" ]; then
+    # The normal state of a fresh clone: .sprint-state/ is a process artifact and
+    # gitignored. Say so, out loud, with the command that would fix it.
+    echo "  ⏭️  Gate 5c: spec/test alignment NOT CHECKED — $req_ids_file missing"
+    echo "     Run 'xp-gate check-alignment' to generate it and enable this gate."
+    GATE_5C_STATUS="SKIP"
+    return 0
+  fi
+
+  # Staleness: a req-ids.json older than the spec it claims to describe would let a
+  # deleted REQ keep its annotations looking valid.
+  if [ -f "specification.yaml" ] && [ "$req_ids_file" -ot "specification.yaml" ]; then
+    echo "  ⏭️  Gate 5c: spec/test alignment NOT CHECKED — req-ids.json is stale"
+    echo "     specification.yaml is newer. Run 'xp-gate check-alignment' to regenerate."
+    GATE_5C_STATUS="SKIP"
+    return 0
+  fi
+
+  local test_files
+  test_files=$(gate_5c_test_files)
+  if [ -z "$test_files" ]; then
+    # Reported rather than silent: without this line the operator cannot tell
+    # "nothing to check" from "the gate is broken" (#585).
+    echo "  ℹ️  Gate 5c: no test files among the staged changes — nothing to align."
+    GATE_5C_STATUS="SKIP"
+    return 0
+  fi
+
+  echo "  → Checking @test REQ-XXX annotations..."
+  local annotation_errors=0 tf req_id found
+  while read -r tf; do
+    [ -n "$tf" ] || continue
+    [ -f "$tf" ] || continue
+    while read -r req_id; do
+      [ -n "$req_id" ] || continue
+      found=$(gate_5c_req_ids "$req_ids_file" | grep -qxF "$req_id" && echo yes || true)
+      if [ -z "$found" ]; then
+        echo "❌ Gate 5c: $tf — @test $req_id: REQ ID not found in specification.yaml"
+        annotation_errors=$((annotation_errors + 1))
+      fi
+    done < <(gate_5c_annotations "$tf")
+  done < <(printf '%s\n' "$test_files")
+
+  if [ "$annotation_errors" -gt 0 ]; then
+    echo ""
+    echo "❌ $annotation_errors test annotation(s) reference non-existent REQ IDs — commit BLOCKED"
+    echo "   Fix: verify the REQ IDs against specification.yaml, or run 'xp-gate check-alignment'"
+    GATE_5C_STATUS="BLOCK"
+    return 1
+  fi
+
+  # Reverse check: REQs with no annotated test among the staged changes. Visible,
+  # non-blocking — a single commit rarely touches every requirement's test.
+  local all_reqs annotated_all="" untested=0 spec_req
+  all_reqs=$(gate_5c_req_ids "$req_ids_file")
+  while read -r tf; do
+    [ -n "$tf" ] || continue
+    [ -f "$tf" ] || continue
+    annotated_all="$annotated_all $(gate_5c_annotations "$tf")"
+  done < <(printf '%s\n' "$test_files")
+
+  while read -r spec_req; do
+    [ -n "$spec_req" ] || continue
+    if ! printf '%s\n' "$annotated_all" | tr ' ' '\n' | grep -qxF "$spec_req"; then
+      untested=$((untested + 1))
+    fi
+  done < <(printf '%s\n' "$all_reqs")
+
+  if [ "$untested" -gt 0 ]; then
+    echo "  ⚠️  [FAIL] Gate 5c: $untested REQ(s) in specification.yaml have no annotated tests"
+    echo "     This is non-blocking. Run 'xp-gate check-alignment' for the full report."
+  fi
+
+  echo "  ✅ @test annotation check complete."
+  GATE_5C_STATUS="PASS"
+  return 0
+}

package/hooks/lib/jscpd-run.sh

@@ -1,12 +1,51 @@
 #!/usr/bin/env bash
 # ============================================================================
-# Gate 2 duplicate-code helpers (issue #477)
+# Gate 2 duplicate-code helpers (issue #477, #591)
 #
 # Extracted from pre-commit so the outcome contract is unit-testable without
 # executing the hook, and so an installed hook can source it the same way it
 # sources the other libraries in this directory.
 # ============================================================================
 
+# The default ignore set: what Gate 2 must NOT treat as refactorable source when
+# the project expresses no preference (#591).
+#
+# jscpd's own defaults treat .yaml, .txt and .log as scannable formats. On a
+# data-heavy project that reports an exemptions manifest, a golden snapshot and
+# two build logs as "duplicate code" — measured as 48.72% duplication on a
+# fixture that contained no source at all. The number is worse than noise: a
+# reader cannot tell "yaml rows that must repeat" from "two methods that were
+# really copy-pasted", so the honest response is to stop reading Gate 2 and take
+# the real duplicates down with it. The reporter's own tally: 176 clones
+# reported, 6 refactorable.
+#
+# Deliberately NARROW. Every entry is a file class whose duplication is its data
+# shape or its artifact nature, never a refactoring target. Real source
+# extensions are untouched — pinned by a control case, because an ignore set that
+# also swallowed .ts/.java/.py would report a permanent clean and look healthier
+# than before the fix.
+JSCPD_DEFAULT_IGNORE_PATTERNS='(^|/)(node_modules|dist|build|target|coverage|out|\.next|\.nuxt|vendor)/|\.log$|\.txt$|\.(ya?ml)$|golden|baseline\.json$|evidence'
+
+# Human-readable form, printed by the gate so the baseline is auditable (#591
+# point 3). Silence about the default is the same defect as silence about a
+# skipped gate: the user cannot answer "what did it scan".
+jscpd_default_ignore_patterns() {
+  printf '%s\n' "jscpd default ignore (no jscpd.conf.json): build output (node_modules, dist, build, target, coverage, out, vendor), *.log, *.txt, *.yaml/*.yml, *golden*, *baseline.json, *evidence*"
+}
+
+# Is this path covered by the default ignore set? Exit 0 = ignore it.
+#
+# XP_GATE_JSCPD_DEFAULT_IGNORE=0 disables the set entirely: a project that
+# genuinely wants YAML compared must be able to say so, or the default would make
+# some real duplicates unreachable.
+jscpd_is_default_ignored() {
+  local _path="$1"
+  if [ "${XP_GATE_JSCPD_DEFAULT_IGNORE:-1}" = "0" ]; then
+    return 1
+  fi
+  printf '%s\n' "$_path" | grep -qE "$JSCPD_DEFAULT_IGNORE_PATTERNS"
+}
+
 # Echo the jscpd config the gate should pass, or nothing when the project has
 # none.
 #

package/hooks/lib/native-path.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# Convert a POSIX path into the form a NATIVE Windows binary can open.
+#
+# #581 / #582: on WSL and in Git-Bash, `node.exe` and `gitleaks.exe` cannot open
+# `/mnt/d/projects/repo/...` or `/d/projects/repo/...`. They resolve a leading `/` to
+# `<current drive>:\`, so the path silently becomes `D:\mnt\d\projects\...` and the
+# module is "not found". The failure then gets reported as a verdict about the USER'S
+# repository:
+#
+#   Gate 9  ❌ BLOCKED - Build integrity check failed
+#           Fix type errors, broken imports, or package manifest issues
+#
+#   Gate 8  ❌ BLOCKED - Secrets detected in staged files
+#
+# Both are wrong, and both are expensive to debug: the message points at the code,
+# the cause is the shell. #582 fixed the Gate 8 instance inline; this library exists so
+# the next caller does not have to re-derive it, and so there is ONE place that knows
+# the converters — not one per gate that happened to notice.
+#
+# Relative paths are deliberately NOT converted. node resolves `scripts/x.cjs` against
+# its own cwd, which it translated correctly; converting would be pointless work and a
+# chance to get it wrong.
+
+# Does this host need POSIX -> native conversion at all?
+#
+# True when a native binary is on the far side of the shell: WSL, or MSYS/Git-Bash on
+# Windows. On a plain Linux/macOS host neither converter exists and no conversion is
+# ever wanted.
+#
+# @returns 0 when conversion applies
+native_path_applies() {
+  [ -n "${WSL_DISTRO_NAME:-}" ] && return 0
+  [ -n "${MSYSTEM:-}" ] && return 0
+  # Fallback: a converter being present IS the signal, and covers hosts that set
+  # neither marker (some CI images strip MSYSTEM).
+  command -v wslpath >/dev/null 2>&1 && return 0
+  command -v cygpath >/dev/null 2>&1 && return 0
+  return 1
+}
+
+# Convert a path to native Windows form, or echo it unchanged when that is not possible.
+#
+# Order matters. `wslpath` is WSL's converter; `cygpath` is MSYS/Git-Bash's. Asking each
+# only on its own host avoids the case where both exist and the wrong one "succeeds"
+# with a path the other binary cannot use.
+#
+# Never fails the caller: a path that cannot be converted is returned as-is, because a
+# gate that aborts here would break on hosts that need no conversion at all. Callers that
+# must know whether conversion happened should compare the input and output.
+#
+# @param {string} path path to convert
+# @returns {string} native form, or the input unchanged
+to_native_path() {
+  local _p="${1:-}"
+  [ -n "$_p" ] || return 0
+  # Only absolute paths are candidates. A relative path is resolved by the child
+  # process against a cwd it handles correctly.
+  case "$_p" in
+    /*) ;;
+    *) printf '%s' "$_p"; return 0 ;;
+  esac
+
+  local _converted=""
+  if [ -n "${WSL_DISTRO_NAME:-}" ] && command -v wslpath >/dev/null 2>&1; then
+    _converted=$(wslpath -w "$_p" 2>/dev/null || true)
+  elif command -v cygpath >/dev/null 2>&1; then
+    _converted=$(cygpath -w "$_p" 2>/dev/null || true)
+  elif command -v wslpath >/dev/null 2>&1; then
+    # wslpath without WSL_DISTRO_NAME: still the better guess than nothing.
+    _converted=$(wslpath -w "$_p" 2>/dev/null || true)
+  fi
+
+  if [ -n "$_converted" ]; then
+    printf '%s' "$_converted"
+  else
+    printf '%s' "$_p"
+  fi
+}
+
+# Convert a path only when conversion is needed, and say so when it cannot be done.
+#
+# The stricter sibling: use this where a wrong path produces a MISLEADING verdict rather
+# than a clean failure (Gate 9's "build integrity check failed", Gate 8's "secrets
+# detected"). It prints a warning to stderr when the path is absolute, the host needs
+# conversion, and nothing was converted — the case that silently becomes a false verdict.
+#
+# @param {string} path path to convert
+# @param {string} what human name for the path, used in the warning
+# @returns {string} converted path, or the input unchanged
+to_native_path_or_warn() {
+  local _p="${1:-}"
+  local _what="${2:-path}"
+  local _out
+  _out=$(to_native_path "$_p")
+  if [ "$_out" = "$_p" ]; then
+    case "$_p" in
+      /*)
+        if native_path_applies; then
+          echo "  ⚠️  could not convert $_what to native form: $_p" >&2
+          echo "      a native binary may fail to open it; the failure will look like a code defect" >&2
+        fi
+        ;;
+    esac
+  fi
+  printf '%s' "$_out"
+}

package/hooks/lib/prepush-score.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Score a pre-push gate list, or refuse to.
+
+`overall.score` is the most quotable number in a pre-push report, so it has to
+generalise over the gates it claims to summarise (#580, #577).
+
+Two shapes must produce no number at all:
+
+    no gate ran            ->  0.0/10 would claim "everything broke"
+    some gate ran, but the  -> 10.0/10 off a single passing gate would claim
+    rest never did             "everything is green"
+
+The honest answer in both cases is None — "not measured" — because either way the
+number would be a claim the run cannot support. A score is emitted only when the
+gates that ran are a MAJORITY of the gates that exist, and it always travels with
+`score_scope` naming what it covers, so no reader can quote it as global quality.
+
+Usage:
+    prepush-score.py --status PASS --status SKIP ...      # one per gate
+    prepush-score.py --report path/to/report.json        # patch in place
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+
+# Statuses grouped by what they say about the run. Kept as data rather than as
+# branches so adding a status is a one-line change and cannot silently fall
+# through to "failed" (which is exactly what DEGRADED used to do, #574).
+FAILED_STATUSES = ("FAIL", "BLOCK")
+# A degradation is a gate that ran but could not fully do its job, so it counts
+# with the warnings: a degraded gate must never be judged a hard failure.
+DEGRADED_STATUSES = ("DEGRADED", "WARN")
+
+
+def _group_by_disposition(gates: Sequence[Dict[str, Any]]) -> Dict[str, List[Dict[str, Any]]]:
+    """Split the gate list into ran / passed / failed / warned / degraded / skipped."""
+    def with_status(statuses: Sequence[str]) -> List[Dict[str, Any]]:
+        return [g for g in gates if g.get("status") in statuses]
+
+    ran = [g for g in gates if g.get("status") != "SKIP"]
+    return {
+        "ran": ran,
+        "passed": with_status(("PASS",)),
+        "failed": with_status(FAILED_STATUSES),
+        "warned": with_status(("WARN",)),
+        "degraded": with_status(DEGRADED_STATUSES),
+        "skipped": with_status(("SKIP",)),
+    }
+
+
+def _score_for(ran: Sequence[Dict[str, Any]], passed_count: int, total: int) -> Tuple[Optional[str], str]:
+    """The score and the scope it covers, or (None, reason) when it cannot apply.
+
+    A score speaks for the gates that ran, so it is only emitted when those can
+    summarise the report. Two shapes cannot:
+
+        nothing ran            -> 0.0/10 would claim "everything broke"
+        fewer than half ran    -> 10.0/10 off one passing gate would claim
+                                  "everything is green"
+
+    Six of twelve is a tie, not an endorsement, hence `* 2 <=`.
+    """
+    if not ran:
+        return None, "not measured"
+    if len(ran) * 2 <= total:
+        return None, "%d of %d gates is too few to summarise" % (len(ran), total)
+    return "%.1f/10" % (10.0 * passed_count / len(ran)), "%d of %d gates" % (len(ran), total)
+
+
+def compute(gates: Sequence[Dict[str, Any]]) -> Dict[str, Any]:
+    """Return the score fields for a gate list.
+
+    Keys: score (str | None), score_scope (str), gates_run, gates_skipped,
+    gates_total, gates_passed, gates_failed, gates_warned, gates_degraded,
+    failed_gates, skipped_gates. The rule lives here and nowhere else.
+
+    `gates_total` and `gates_passed` are counted from the list rather than taken
+    from the caller: they used to be a hardcoded 8 and a 1/0 squashed out of the
+    verdict, so a report could claim eight gates while listing twelve (#569).
+    """
+    total = len(gates)
+    groups = _group_by_disposition(gates)
+    score, scope = _score_for(groups["ran"], len(groups["passed"]), total)
+
+    return {
+        "score": score,
+        "score_scope": scope,
+        "gates_run": len(groups["ran"]),
+        "gates_skipped": len(groups["skipped"]),
+        "gates_total": total,
+        "gates_passed": len(groups["passed"]),
+        "gates_failed": len(groups["failed"]),
+        "gates_warned": len(groups["warned"]),
+        "gates_degraded": len(groups["degraded"]),
+        "failed_gates": [g.get("id") for g in groups["failed"]],
+        "skipped_gates": [g.get("id") for g in groups["skipped"]],
+    }
+
+
+def apply_to_report(report: Dict[str, Any]) -> Dict[str, Any]:
+    """Patch the score fields into a report's `overall` section, in place."""
+    overall = report.setdefault("overall", {})
+    overall.update(compute(report.get("gates", [])))
+    return report
+
+
+def main(argv: Optional[Iterable[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description="Score a pre-push gate list.")
+    parser.add_argument(
+        "--status",
+        action="append",
+        default=[],
+        metavar="STATUS",
+        help="status of one gate (repeatable, in gate order)",
+    )
+    parser.add_argument(
+        "--report",
+        metavar="PATH",
+        help="patch the score fields into this report JSON in place",
+    )
+    args = parser.parse_args(list(argv) if argv is not None else None)
+
+    if args.report:
+        path = Path(args.report)
+        report = json.loads(path.read_text(encoding="utf-8"))
+        apply_to_report(report)
+        path.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+        return 0
+
+    if not args.status:
+        parser.error("either --report or at least one --status is required")
+
+    print(json.dumps(compute([{"status": s} for s in args.status])))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/lib/sprint-gate-report.sh

@@ -56,3 +56,26 @@ sprint_gate_detail() {
   done
   return 0
 }
+
+# Echo WHY sprint-gate.sh allowed the commit (#584).
+#
+# `allow` on its own is ambiguous: it certifies a validated sprint, but it also
+# covers "the sprint has not reached this gate's phase" and "no JSON parser, so
+# nothing could be read". pre-commit mapped every one of those to Gate 11 PASS,
+# so a gate that examined nothing raised the score and left the verdict alone.
+#
+# Only `checks-passed` licenses a PASS. Anything else -- including an `allow`
+# from an older sprint-gate.sh that carries no reason at all -- means "not
+# evaluated", and the caller must report SKIP. Defaulting the other way would
+# reinstate the defect for every consumer who has not re-installed.
+sprint_gate_allow_reason() {
+  local _out="${1:-}" _reason
+  _reason=$(printf '%s' "$_out" | sed -n 's/.*"allow_reason"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | tail -1)
+  if [ -n "$_reason" ]; then
+    printf '%s\n' "$_reason"
+    return 0
+  fi
+  # No reason given. The decision may still be an `allow`; the caller decides.
+  printf 'unspecified\n'
+  return 0
+}