feat: Core Contracts - Define all package interfaces

src/Contracts/CheckRunQueryInterface.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\Contracts;
+
+use ConduitUI\Pr\DataTransferObjects\CheckRun;
+use ConduitUI\Pr\DataTransferObjects\CheckSummary;
+use Illuminate\Support\Collection;
+
+/**
+ * Contract for querying check runs
+ */
+interface CheckRunQueryInterface
+{
+    /**
+     * @return Collection<int, CheckRun>
+     */
+    public function get(): Collection;
+
+    /**
+     * @return Collection<int, CheckRun>
+     */
+    public function wherePassing(): Collection;
+
+    /**
+     * @return Collection<int, CheckRun>
+     */
+    public function whereFailing(): Collection;
+
+    /**
+     * @return Collection<int, CheckRun>
+     */
+    public function wherePending(): Collection;
+
+    /**
+     * @return Collection<int, CheckRun>
+     */
+    public function whereNeutral(): Collection;
+
+    /**
+     * @return Collection<int, CheckRun>
+     */
+    public function whereSkipped(): Collection;
+
+    public function latest(): ?CheckRun;
+
+    public function byName(string $name): ?CheckRun;
+
+    public function summary(): CheckSummary;
+}

src/Contracts/CommentManagerInterface.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\Contracts;
+
+use ConduitUI\Pr\DataTransferObjects\Comment;
+use Illuminate\Support\Collection;
+
+/**
+ * Contract for managing comments
+ */
+interface CommentManagerInterface
+{
+    /**
+     * @return Collection<int, Comment>
+     */
+    public function get(): Collection;
+
+    public function create(string $body): Comment;
+
+    public function update(int $commentId, string $body): Comment;
+
+    public function delete(int $commentId): bool;
+}

src/Contracts/FileQueryInterface.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\Contracts;
+
+use ConduitUI\Pr\DataTransferObjects\File;
+use ConduitUI\Pr\DataTransferObjects\FileStats;
+use Illuminate\Support\Collection;
+
+/**
+ * Contract for querying changed files
+ */
+interface FileQueryInterface
+{
+    /**
+     * @return Collection<int, File>
+     */
+    public function get(): Collection;
+
+    /**
+     * @return Collection<int, File>
+     */
+    public function whereAdded(): Collection;
+
+    /**
+     * @return Collection<int, File>
+     */
+    public function whereModified(): Collection;
+
+    /**
+     * @return Collection<int, File>
+     */
+    public function whereRemoved(): Collection;
+
+    /**
+     * @return Collection<int, File>
+     */
+    public function whereRenamed(): Collection;
+
+    /**
+     * @param  string  $pattern  Glob pattern for file paths
+     * @return Collection<int, File>
+     */
+    public function wherePath(string $pattern): Collection;
+
+    /**
+     * @return Collection<int, File>
+     */
+    public function whereExtension(string $extension): Collection;
+
+    public function stats(): FileStats;
+}

src/Contracts/MergeManagerInterface.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\Contracts;
+
+use ConduitUI\Pr\DataTransferObjects\PullRequest;
+
+/**
+ * Contract for merge operations
+ */
+interface MergeManagerInterface
+{
+    public function merge(?string $commitTitle = null, ?string $commitMessage = null): PullRequest;
+
+    public function squash(?string $commitTitle = null, ?string $commitMessage = null): PullRequest;
+
+    public function rebase(): PullRequest;
+
+    public function canMerge(): bool;
+
+    public function deleteBranch(): bool;
+}

src/Contracts/PullRequestBuilderInterface.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\Contracts;
+
+use ConduitUI\Pr\DataTransferObjects\PullRequest;
+
+/**
+ * Contract for creating pull requests
+ */
+interface PullRequestBuilderInterface
+{
+    public function title(string $title): self;
+
+    public function body(string $body): self;
+
+    public function head(string $branch): self;
+
+    public function base(string $branch): self;
+
+    public function draft(bool $draft = true): self;
+
+    public function maintainerCanModify(bool $allowed = true): self;
+
+    public function create(): PullRequest;
+}

src/Contracts/PullRequestManagerInterface.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\Contracts;
+
+use ConduitUI\Pr\DataTransferObjects\PullRequest;
+
+/**
+ * Contract for managing pull requests
+ */
+interface PullRequestManagerInterface
+{
+    public function find(int $number): PullRequest;
+
+    public function get(int $number): PullRequest;
+
+    public function query(): PullRequestQueryInterface;
+
+    public function create(): PullRequestBuilderInterface;
+}

src/Contracts/ReviewQueryInterface.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\Contracts;
+
+use ConduitUI\Pr\DataTransferObjects\Review;
+use Illuminate\Support\Collection;
+
+/**
+ * Contract for querying reviews
+ */
+interface ReviewQueryInterface
+{
+    /**
+     * @return Collection<int, Review>
+     */
+    public function get(): Collection;
+
+    /**
+     * @return Collection<int, Review>
+     */
+    public function whereApproved(): Collection;
+
+    /**
+     * @return Collection<int, Review>
+     */
+    public function whereChangesRequested(): Collection;
+
+    /**
+     * @return Collection<int, Review>
+     */
+    public function wherePending(): Collection;
+
+    /**
+     * @return Collection<int, Review>
+     */
+    public function byUser(string $username): Collection;
+
+    public function latest(): ?Review;
+}

src/DataTransferObjects/CheckSummary.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\DataTransferObjects;
+
+class CheckSummary
+{
+    public function __construct(
+        public readonly int $total,
+        public readonly int $passing,
+        public readonly int $failing,
+        public readonly int $pending,
+        public readonly int $neutral,
+        public readonly int $skipped,
+    ) {}
+
+    /**
+     * @param  array{total: int, passing: int, failing: int, pending: int, neutral: int, skipped: int}  $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            total: $data['total'],
+            passing: $data['passing'],
+            failing: $data['failing'],
+            pending: $data['pending'],
+            neutral: $data['neutral'],
+            skipped: $data['skipped'],
+        );
+    }
+
+    public function allPassing(): bool
+    {
+        return $this->total > 0 && $this->failing === 0 && $this->pending === 0;
+    }
+
+    public function hasFailures(): bool
+    {
+        return $this->failing > 0;
+    }
+
+    public function hasPending(): bool
+    {
+        return $this->pending > 0;
+    }
+
+    /**
+     * @return array<string, int>
+     */
+    public function toArray(): array
+    {
+        return [
+            'total' => $this->total,
+            'passing' => $this->passing,
+            'failing' => $this->failing,
+            'pending' => $this->pending,
+            'neutral' => $this->neutral,
+            'skipped' => $this->skipped,
+        ];
+    }
+}

src/DataTransferObjects/FileStats.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\DataTransferObjects;
+
+class FileStats
+{
+    public function __construct(
+        public readonly int $total,
+        public readonly int $added,
+        public readonly int $modified,
+        public readonly int $removed,
+        public readonly int $renamed,
+        public readonly int $totalAdditions,
+        public readonly int $totalDeletions,
+        public readonly int $totalChanges,
+    ) {}
+
+    /**
+     * @param  array{total: int, added: int, modified: int, removed: int, renamed: int, total_additions: int, total_deletions: int, total_changes: int}  $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            total: $data['total'],
+            added: $data['added'],
+            modified: $data['modified'],
+            removed: $data['removed'],
+            renamed: $data['renamed'],
+            totalAdditions: $data['total_additions'],
+            totalDeletions: $data['total_deletions'],
+            totalChanges: $data['total_changes'],
+        );
+    }
+
+    /**
+     * @return array<string, int>
+     */
+    public function toArray(): array
+    {
+        return [
+            'total' => $this->total,
+            'added' => $this->added,
+            'modified' => $this->modified,
+            'removed' => $this->removed,
+            'renamed' => $this->renamed,
+            'total_additions' => $this->totalAdditions,
+            'total_deletions' => $this->totalDeletions,
+            'total_changes' => $this->totalChanges,
+        ];
+    }
+}