@matt82198/aesop 0.1.0 → 0.3.1

package/tools/ci_merge_wait.py

@@ -1,21 +1,27 @@
 #!/usr/bin/env python3
 """
-ci_merge_wait.py — CI-gated merge helper: wait for PR checks to conclude, then merge.
+ci_merge_wait.py - CI-gated merge helper: wait for PR checks to conclude, then merge.
 
 Polls gh pr view until all status checks conclude (SUCCESS/FAILURE), then merges ONLY
 if all checks are SUCCESS. The gh pr merge call is STRUCTURALLY UNREACHABLE unless the
-status is SUCCESS — this is the whole point (prevents merge-on-CI-failure edge cases).
+status is SUCCESS - this is the whole point (prevents merge-on-CI-failure edge cases).
+
+Fail-closed semantics: empty rollup -> PENDING by default; use --allow-no-checks to treat
+empty rollups as SUCCESS. Use --expect-checks to require specific named checks to be present
+and successful before merging.
 
 Usage:
   python ci_merge_wait.py <PR-number> [--timeout SECONDS] [--poll SECONDS] [--merge-method merge|squash|rebase]
-                          [--dry-run] [--self-test]
+                          [--dry-run] [--allow-no-checks] [--expect-checks NAME1,NAME2,...] [--self-test]
 
 Options:
-  --timeout SECONDS      Max seconds to wait for CI to conclude (default: 3600)
-  --poll SECONDS         Poll interval in seconds (default: 10)
-  --merge-method METHOD  Merge strategy: merge, squash, rebase (default: merge)
-  --dry-run              Skip actual merge, just verify CI status and report what would happen
-  --self-test            Run offline self-test of polling/decision logic (no network, no PR required)
+  --timeout SECONDS              Max seconds to wait for CI (default: 3600)
+  --poll SECONDS                 Poll interval in seconds (default: 10)
+  --merge-method METHOD          Merge strategy: merge, squash, rebase (default: merge)
+  --dry-run                      Skip actual merge, just verify CI status and report what would happen
+  --allow-no-checks              Allow merge when no CI checks present (repos without CI)
+  --expect-checks NAME1,NAME2    Comma-separated list of checks that MUST be present and successful
+  --self-test                    Run offline self-test of polling/decision logic (no network, no PR required)
 
 Exit codes:
   0 = PR merged successfully, dry-run verified, or self-test passed
@@ -73,7 +79,7 @@ def get_pr_status(pr_number):
     return data
 
 
-def check_ci_status(status_rollup):
+def check_ci_status(status_rollup, allow_no_checks=False, expected_checks=None):
     """
     Analyze status check rollup from gh pr view --json statusCheckRollup.
     Handles both CheckRun (status + conclusion) and StatusContext (state) entries.
@@ -95,15 +101,35 @@ def check_ci_status(status_rollup):
 
     GitHub semantics: NEUTRAL and SKIPPED conclusions/states are non-blocking and do not prevent merge.
 
+    Empty rollup (fail-closed):
+      - If allow_no_checks=True: ("success", None)
+      - If allow_no_checks=False: ("pending", None) [fail-closed default]
+
+    Expected checks (if provided):
+      - ALL named checks must be present in rollup
+      - ALL named checks must be in SUCCESS state
+      - If any expected check is missing: ("pending", None)
+      - If any expected check fails: ("failure", check_name)
+
+    Args:
+      status_rollup: list of check dicts from gh pr view
+      allow_no_checks: if True, empty rollup → success; if False (default), empty rollup → pending
+      expected_checks: set of check names that MUST be present and successful
+
     Returns: ("pending", None), ("success", None), or ("failure", check_name)
     """
+    # Fail-closed: empty rollup defaults to PENDING unless explicitly allowed
     if not status_rollup:
-        # No checks (unusual but treat as success)
-        return ("success", None)
+        if allow_no_checks:
+            return ("success", None)
+        else:
+            # Empty rollup: fail-closed to PENDING (window where checks vanished/haven't registered yet)
+            return ("pending", None)
 
     # Collect statuses
     pending_checks = []
     failed_checks = []
+    found_checks = {}  # Map of check name → status
 
     for check in status_rollup:
         check_name = check.get("name", "unknown")
@@ -117,10 +143,16 @@ def check_ci_status(status_rollup):
 
             if status == "COMPLETED":
                 # Check conclusion for failure indicators
-                if conclusion and conclusion.upper() in ("FAILURE", "CANCELLED", "TIMED_OUT", "ACTION_REQUIRED", "STARTUP_FAILURE"):
+                if conclusion and conclusion.upper() in ("FAILURE", "CANCELLED", "TIMED_OUT", "ACTION_REQUIRED", "STARTUP_FAILURE", "STALE"):
                     check_status = "failure"
+                elif not conclusion or conclusion == "":
+                    # COMPLETED with null/empty conclusion = fail-closed to PENDING (API anomaly)
+                    check_status = "pending"
+                elif conclusion.upper() in ("NEUTRAL", "SKIPPED"):
+                    # Non-blocking advisory or skipped checks
+                    check_status = "success"
                 else:
-                    # COMPLETED with no/empty conclusion or other conclusion = success
+                    # Other conclusion values (unknown) = success (GitHub default)
                     check_status = "success"
             elif status in ("QUEUED", "IN_PROGRESS"):
                 check_status = "pending"
@@ -148,13 +180,44 @@ def check_ci_status(status_rollup):
             # Unrecognized shape (no status or state field) - fail-closed
             check_status = "pending"
 
+        # Record this check's status
+        found_checks[check_name] = check_status
+
         # Collect check status
         if check_status == "failure":
             failed_checks.append(check_name)
         elif check_status == "pending":
             pending_checks.append(check_name)
 
-    # Determine overall status
+    # If expected checks provided, verify all are present and successful
+    if expected_checks:
+        for expected_name in expected_checks:
+            if expected_name not in found_checks:
+                # Expected check not found (missing in the window)
+                return ("pending", None)
+            if found_checks[expected_name] == "failure":
+                # Expected check failed
+                return ("failure", expected_name)
+            if found_checks[expected_name] == "pending":
+                # Expected check still pending
+                return ("pending", None)
+
+        # All expected checks passed - warn about any non-expected check failures but don't block
+        # Non-expected checks are informational/flaky third-party checks; they should not gate merge
+        non_expected_failures = []
+        for check_name, check_status in found_checks.items():
+            if check_name not in expected_checks and check_status == "failure":
+                non_expected_failures.append(check_name)
+
+        if non_expected_failures:
+            # Log the failures loudly but don't block merge
+            print(f"WARNING: Non-expected check(s) failed (informational, does not block merge): {', '.join(non_expected_failures)}")
+
+        # All expected checks passed - merge is allowed even if non-expected checks are failing
+        # (pending non-expected checks are also acceptable)
+        return ("success", None)
+
+    # Determine overall status (when expected_checks is not specified)
     if failed_checks:
         return ("failure", failed_checks[0])
     elif pending_checks:
@@ -191,17 +254,17 @@ def run_self_test():
     """
     print("Running self-test with real GitHub API payloads...")
 
-    # Test 1: CheckRun success case (COMPLETED with no conclusion)
+    # Test 1: CheckRun success case (COMPLETED with explicit success conclusion)
     checkrun_success = [
-        {"name": "test-unit", "status": "COMPLETED", "conclusion": None},
-        {"name": "test-integration", "status": "COMPLETED", "conclusion": ""},
-        {"name": "lint", "status": "COMPLETED", "conclusion": None},
+        {"name": "test-unit", "status": "COMPLETED", "conclusion": "SUCCESS"},
+        {"name": "test-integration", "status": "COMPLETED", "conclusion": "SUCCESS"},
+        {"name": "lint", "status": "COMPLETED", "conclusion": None},  # null conclusion = fail-closed to PENDING
     ]
     ci_status, failed_check = check_ci_status(checkrun_success)
-    if ci_status != "success":
-        print(f"FAIL: Expected 'success' for CheckRun COMPLETED, got '{ci_status}'")
+    if ci_status != "pending":
+        print(f"FAIL: Expected 'pending' for COMPLETED with null conclusion (fail-closed), got '{ci_status}'")
         return False
-    print("[OK] CheckRun success case (COMPLETED + no conclusion)")
+    print("[OK] CheckRun with null conclusion fails-closed to PENDING")
 
     # Test 2: CheckRun in-progress case (should be pending)
     checkrun_pending = [
@@ -257,7 +320,7 @@ def run_self_test():
 
     # Test 7: Mixed CheckRun and StatusContext (all success)
     mixed_success = [
-        {"name": "test-unit", "status": "COMPLETED", "conclusion": None},
+        {"name": "test-unit", "status": "COMPLETED", "conclusion": "SUCCESS"},
         {"name": "travis-ci", "state": "success"},
     ]
     ci_status, _ = check_ci_status(mixed_success)
@@ -268,7 +331,7 @@ def run_self_test():
 
     # Test 8: Mixed payloads with pending (should block merge)
     mixed_pending = [
-        {"name": "test-unit", "status": "COMPLETED", "conclusion": None},
+        {"name": "test-unit", "status": "COMPLETED", "conclusion": "SUCCESS"},
         {"name": "lint", "status": "QUEUED", "conclusion": None},
     ]
     ci_status, _ = check_ci_status(mixed_pending)
@@ -277,14 +340,21 @@ def run_self_test():
         return False
     print("[OK] Mixed payloads with QUEUED (pending)")
 
-    # Test 9: No checks (treat as success)
+    # Test 9: Empty checks array (fail-closed: should be PENDING by default)
     ci_status, _ = check_ci_status([])
+    if ci_status != "pending":
+        print(f"FAIL: Expected 'pending' for empty rollup (fail-closed), got '{ci_status}'")
+        return False
+    print("[OK] Empty rollup case: treated as PENDING (fail-closed)")
+
+    # Test 10: Empty checks array with --allow-no-checks flag (should be SUCCESS)
+    ci_status, _ = check_ci_status([], allow_no_checks=True)
     if ci_status != "success":
-        print(f"FAIL: Expected 'success' for no checks, got '{ci_status}'")
+        print(f"FAIL: Expected 'success' for empty rollup with allow_no_checks=True, got '{ci_status}'")
         return False
-    print("[OK] No-checks case: treated as success")
+    print("[OK] Empty rollup with allow_no_checks=True: treated as SUCCESS")
 
-    # Test 10: Unrecognized shape (fail-closed: should not succeed)
+    # Test 11: Unrecognized shape (fail-closed: should not succeed)
     unrecognized = [
         {"name": "mystery-check"},
     ]
@@ -294,7 +364,7 @@ def run_self_test():
         return False
     print("[OK] Unrecognized check shape (fail-closed)")
 
-    # Test 11: CheckRun cancelled (counts as failure)
+    # Test 12: CheckRun cancelled (counts as failure)
     cancelled_check = [
         {"name": "test-unit", "status": "COMPLETED", "conclusion": "CANCELLED"},
     ]
@@ -304,7 +374,7 @@ def run_self_test():
         return False
     print("[OK] CheckRun CANCELLED (failure)")
 
-    # Test 12: CheckRun neutral conclusion (non-blocking advisory, should be success)
+    # Test 13: CheckRun neutral conclusion (non-blocking advisory, should be success)
     neutral_check = [
         {"name": "advisory-lint", "status": "COMPLETED", "conclusion": "NEUTRAL"},
     ]
@@ -314,7 +384,7 @@ def run_self_test():
         return False
     print("[OK] CheckRun NEUTRAL conclusion (success, non-blocking)")
 
-    # Test 13: CheckRun skipped conclusion (non-blocking, should be success)
+    # Test 14: CheckRun skipped conclusion (non-blocking, should be success)
     skipped_check = [
         {"name": "optional-test", "status": "COMPLETED", "conclusion": "SKIPPED"},
     ]
@@ -324,7 +394,7 @@ def run_self_test():
         return False
     print("[OK] CheckRun SKIPPED conclusion (success, non-blocking)")
 
-    # Test 14: StatusContext neutral state (non-blocking advisory, should be success)
+    # Test 15: StatusContext neutral state (non-blocking advisory, should be success)
     neutral_state = [
         {"name": "advisory-check", "state": "neutral"},
     ]
@@ -334,7 +404,7 @@ def run_self_test():
         return False
     print("[OK] StatusContext neutral state (success, non-blocking)")
 
-    # Test 15: StatusContext skipped state (non-blocking, should be success)
+    # Test 16: StatusContext skipped state (non-blocking, should be success)
     skipped_state = [
         {"name": "optional-check", "state": "skipped"},
     ]
@@ -344,7 +414,7 @@ def run_self_test():
         return False
     print("[OK] StatusContext skipped state (success, non-blocking)")
 
-    # Test 16: Fabricated unknown state (fail-closed to pending)
+    # Test 17: Fabricated unknown state (fail-closed to pending)
     unknown_state = [
         {"name": "mystery-state", "state": "fabricated_unknown_state"},
     ]
@@ -354,6 +424,133 @@ def run_self_test():
         return False
     print("[OK] Fabricated unknown state (pending, fail-closed)")
 
+    # Test 18: Expected checks - all present and successful
+    rollup_with_expected = [
+        {"name": "unit-tests", "status": "COMPLETED", "conclusion": "SUCCESS"},
+        {"name": "integration-tests", "status": "COMPLETED", "conclusion": "SUCCESS"},
+        {"name": "lint", "status": "COMPLETED", "conclusion": "SUCCESS"},
+    ]
+    ci_status, _ = check_ci_status(
+        rollup_with_expected,
+        expected_checks={"unit-tests", "integration-tests"}
+    )
+    if ci_status != "success":
+        print(f"FAIL: Expected 'success' with expected checks present, got '{ci_status}'")
+        return False
+    print("[OK] Expected checks all present and successful")
+
+    # Test 19: Expected checks - one missing (should be PENDING)
+    rollup_missing_expected = [
+        {"name": "unit-tests", "status": "COMPLETED", "conclusion": "SUCCESS"},
+        {"name": "lint", "status": "COMPLETED", "conclusion": "SUCCESS"},
+    ]
+    ci_status, _ = check_ci_status(
+        rollup_missing_expected,
+        expected_checks={"unit-tests", "integration-tests"}
+    )
+    if ci_status != "pending":
+        print(f"FAIL: Expected 'pending' with missing expected check, got '{ci_status}'")
+        return False
+    print("[OK] Missing expected check (window transition): returns PENDING")
+
+    # Test 20: Expected checks - one failed (should be FAILURE)
+    rollup_failed_expected = [
+        {"name": "unit-tests", "status": "COMPLETED", "conclusion": "FAILURE"},
+        {"name": "integration-tests", "status": "COMPLETED", "conclusion": "SUCCESS"},
+    ]
+    ci_status, failed_check = check_ci_status(
+        rollup_failed_expected,
+        expected_checks={"unit-tests", "integration-tests"}
+    )
+    if ci_status != "failure" or failed_check != "unit-tests":
+        print(f"FAIL: Expected 'failure' with expected check failed, got '{ci_status}' / '{failed_check}'")
+        return False
+    print("[OK] Expected check failed: returns FAILURE")
+
+    # Test 20b: Expected checks all pass, but non-expected check FAILED (P2 audit bug fix)
+    # FIXED: When --expect-checks is given, non-expected failures should NOT block merge.
+    # Non-expected checks are informational/flaky third-party checks; only expected checks gate merge.
+    # The failure is logged loudly as a warning, but merge is allowed.
+    rollup_expected_pass_noncxpected_fail = [
+        {"name": "unit-tests", "status": "COMPLETED", "conclusion": "SUCCESS"},
+        {"name": "integration-tests", "status": "COMPLETED", "conclusion": "SUCCESS"},
+        {"name": "lint", "status": "COMPLETED", "conclusion": "FAILURE"},
+    ]
+    ci_status, failed_check = check_ci_status(
+        rollup_expected_pass_noncxpected_fail,
+        expected_checks={"unit-tests", "integration-tests"}
+    )
+    if ci_status != "success":
+        print(f"FAIL: Expected 'success' with non-expected check failed (audit P2 fix), got '{ci_status}'")
+        return False
+    print("[OK] Non-expected check failed while expected pass: returns SUCCESS with warning (P2 audit fix)")
+
+    # Test 20c: Expected checks all pass, non-expected pending is OK (does not block)
+    rollup_expected_pass_noncexpected_pending = [
+        {"name": "unit-tests", "status": "COMPLETED", "conclusion": "SUCCESS"},
+        {"name": "integration-tests", "status": "COMPLETED", "conclusion": "SUCCESS"},
+        {"name": "optional-scan", "status": "IN_PROGRESS", "conclusion": None},
+    ]
+    ci_status, _ = check_ci_status(
+        rollup_expected_pass_noncexpected_pending,
+        expected_checks={"unit-tests", "integration-tests"}
+    )
+    if ci_status != "success":
+        print(f"FAIL: Expected 'success' when all expected pass + non-expected pending, got '{ci_status}'")
+        return False
+    print("[OK] Expected all pass, non-expected pending: returns SUCCESS (pending non-expected is OK)")
+
+    # Test 22: CheckRun STALE conclusion (invalidated check, counts as failure)
+    stale_check = [
+        {"name": "ci-run", "status": "COMPLETED", "conclusion": "STALE"},
+    ]
+    ci_status, _ = check_ci_status(stale_check)
+    if ci_status != "failure":
+        print(f"FAIL: Expected 'failure' for STALE conclusion, got '{ci_status}'")
+        return False
+    print("[OK] CheckRun STALE conclusion (failure, invalidated by force-push)")
+
+    # Test 23: CheckRun COMPLETED with null conclusion (API anomaly, fail-closed)
+    null_conclusion_check = [
+        {"name": "test-suite", "status": "COMPLETED", "conclusion": None},
+    ]
+    ci_status, _ = check_ci_status(null_conclusion_check)
+    if ci_status != "pending":
+        print(f"FAIL: Expected 'pending' for COMPLETED + null conclusion (fail-closed), got '{ci_status}'")
+        return False
+    print("[OK] CheckRun COMPLETED + null conclusion fails-closed to PENDING")
+
+    # Test 21: Superseded-run window simulation (old checks vanish, new pending appear)
+    # First: old run had checks that completed successfully
+    old_run_checks = [
+        {"name": "build", "status": "COMPLETED", "conclusion": "SUCCESS"},
+        {"name": "test", "status": "COMPLETED", "conclusion": "SUCCESS"},
+    ]
+    ci_status, _ = check_ci_status(old_run_checks)
+    if ci_status != "success":
+        print(f"FAIL: Old run checks should be success, got '{ci_status}'")
+        return False
+
+    # Second: transition window where old checks vanished and new run hasn't registered yet
+    # Empty rollup should return PENDING (fail-closed)
+    empty_window = []
+    ci_status, _ = check_ci_status(empty_window)
+    if ci_status != "pending":
+        print(f"FAIL: Transition window (empty rollup) should be PENDING (fail-closed), got '{ci_status}'")
+        return False
+
+    # Third: new run appears with pending checks
+    new_run_checks = [
+        {"name": "build", "status": "IN_PROGRESS", "conclusion": None},
+        {"name": "test", "status": "QUEUED", "conclusion": None},
+    ]
+    ci_status, _ = check_ci_status(new_run_checks)
+    if ci_status != "pending":
+        print(f"FAIL: New run pending checks should be PENDING, got '{ci_status}'")
+        return False
+
+    print("[OK] Superseded-run window simulation: transitions correctly")
+
     print("\nAll self-tests passed!")
     return True
 
@@ -393,6 +590,17 @@ def main():
         action="store_true",
         help="Skip actual merge, just verify CI status and report what would happen"
     )
+    parser.add_argument(
+        "--allow-no-checks",
+        action="store_true",
+        help="Allow merge when no CI checks present (repos without CI)"
+    )
+    parser.add_argument(
+        "--expect-checks",
+        type=str,
+        default=None,
+        help="Comma-separated list of checks that MUST be present and successful"
+    )
     parser.add_argument(
         "--self-test",
         action="store_true",
@@ -422,6 +630,11 @@ def main():
         print("ERROR: timeout and poll must be positive")
         sys.exit(1)
 
+    # Parse expected checks
+    expected_checks = None
+    if args.expect_checks:
+        expected_checks = set(c.strip() for c in args.expect_checks.split(",") if c.strip())
+
     # Fetch initial PR status
     print(f"Checking PR #{args.pr_number} status...")
     status = get_pr_status(args.pr_number)
@@ -452,7 +665,11 @@ def main():
             sys.exit(1)
 
         status_rollup = status.get("statusCheckRollup", [])
-        ci_status, failed_check = check_ci_status(status_rollup)
+        ci_status, failed_check = check_ci_status(
+            status_rollup,
+            allow_no_checks=args.allow_no_checks,
+            expected_checks=expected_checks
+        )
 
         if ci_status == "failure":
             print(f"CI FAILED: {failed_check}")
@@ -466,7 +683,11 @@ def main():
                 sys.exit(1)
 
             final_rollup = final_check.get("statusCheckRollup", [])
-            final_ci_status, final_failed = check_ci_status(final_rollup)
+            final_ci_status, final_failed = check_ci_status(
+                final_rollup,
+                allow_no_checks=args.allow_no_checks,
+                expected_checks=expected_checks
+            )
 
             if final_ci_status != "success":
                 print(f"CI STATUS CHANGED: {final_failed}")