feat: add getCheckRunByName to look up check run ID by commit ref and name

Author: HarshMN2345

src/VCS/Adapter.php

@@ -266,6 +266,15 @@ public function createCheckRun(
         throw new \Exception('createCheckRun() is not implemented for ' . $this->getName());
     }
 
+    /**
+     * Finds the most recent check run on a commit by name.
+     * Returns the check run ID, or 0 if none found.
+     */
+    public function getCheckRunByName(string $owner, string $repositoryName, string $ref, string $checkName): int
+    {
+        throw new \Exception('getCheckRunByName() is not implemented for ' . $this->getName());
+    }
+
     /**
      * Gets a check run by ID.
      *

src/VCS/Adapter/Git/GitHub.php

@@ -955,6 +955,29 @@ public function createCheckRun(
         return $response['body'] ?? [];
     }
 
+    /**
+     * Finds the most recent check run on a commit by name.
+     * Returns the check run ID, or 0 if none found.
+     */
+    public function getCheckRunByName(string $owner, string $repositoryName, string $ref, string $checkName): int
+    {
+        $url = "/repos/$owner/$repositoryName/commits/$ref/check-runs";
+
+        $response = $this->call(self::METHOD_GET, $url, ['Authorization' => "Bearer $this->accessToken"], [
+            'check_name' => $checkName,
+            'per_page'   => 1,
+        ]);
+
+        $responseHeadersStatusCode = $response['headers']['status-code'] ?? 0;
+        if ($responseHeadersStatusCode >= 400) {
+            return 0;
+        }
+
+        $runs = $response['body']['check_runs'] ?? [];
+
+        return (int) ($runs[0]['id'] ?? 0);
+    }
+
     /**
      * Gets a check run by ID.
      *