Define key agent interfaces for PRs and issues

.github/workflows/ci.yml

@@ -39,3 +39,24 @@ jobs:
 
       - name: Run tests
         run: vendor/bin/pest
+
+  coverage:
+    runs-on: ubuntu-latest
+    name: Code Coverage
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.3
+          extensions: dom, curl, libxml, mbstring, zip
+          coverage: pcov
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-interaction --no-progress
+
+      - name: Run tests with coverage
+        run: vendor/bin/pest --coverage --min=100

composer.json

@@ -17,7 +17,10 @@
     "require-dev": {
         "laravel/pint": "^1.0",
         "pestphp/pest": "^3.0",
-        "phpstan/phpstan": "^1.0"
+        "phpstan/extension-installer": "*",
+        "phpstan/phpstan": "^1.0",
+        "phpstan/phpstan-deprecation-rules": "^1.2",
+        "phpstan/phpstan-strict-rules": "^1.6"
     },
     "autoload": {
         "psr-4": {
@@ -40,7 +43,8 @@
         "preferred-install": "dist",
         "optimize-autoloader": true,
         "allow-plugins": {
-            "pestphp/pest-plugin": true
+            "pestphp/pest-plugin": true,
+            "phpstan/extension-installer": true
         }
     },
     "extra": {

phpstan.neon

@@ -1,12 +1,10 @@
 parameters:
-    level: 8
+    level: 9
     paths:
         - src
     excludePaths:
         # Excluded because it depends on Laravel's ServiceProvider which isn't available
         # in the non-Laravel test environment. The class is only used in Laravel apps.
         - src/PrServiceProvider.php
     tmpDir: build/phpstan
-    ignoreErrors:
-        -
-            identifier: missingType.iterableValue
+    reportUnmatchedIgnoredErrors: true

phpunit.xml

@@ -15,5 +15,9 @@
         <include>
             <directory>src</directory>
         </include>
+        <exclude>
+            <file>src/PrServiceProvider.php</file>
+            <directory>src/Contracts</directory>
+        </exclude>
     </source>
 </phpunit>

src/Contracts/Assignable.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\Contracts;
+
+/**
+ * Interface for entities that can have assignees.
+ *
+ * Implemented by: Issue, PullRequest
+ */
+interface Assignable
+{
+    /**
+     * Assign users to this entity.
+     *
+     * @param  array<int, string>  $assignees  Usernames to assign
+     */
+    public function assign(array $assignees): static;
+
+    /**
+     * Remove assignees from this entity.
+     *
+     * @param  array<int, string>  $assignees  Usernames to unassign
+     */
+    public function unassign(array $assignees): static;
+}

src/Contracts/Auditable.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\Contracts;
+
+/**
+ * Interface for entities that have an audit trail / timeline.
+ *
+ * Implemented by: Issue, PullRequest
+ */
+interface Auditable
+{
+    /**
+     * Get the timeline of events for this entity.
+     *
+     * @return array<int, mixed>
+     */
+    public function timeline(): array;
+}

src/Contracts/Checkable.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\Contracts;
+
+use ConduitUI\Pr\DataTransferObjects\CheckRun;
+
+/**
+ * Interface for entities that can have CI check runs.
+ *
+ * Implemented by: PullRequest (via head commit), Commit
+ */
+interface Checkable
+{
+    /**
+     * Get all check runs for this entity.
+     *
+     * @return array<int, CheckRun>
+     */
+    public function checks(): array;
+}

src/Contracts/Closeable.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\Contracts;
+
+/**
+ * Interface for entities that can be opened and closed.
+ *
+ * Implemented by: Issue, PullRequest
+ */
+interface Closeable
+{
+    /**
+     * Close this entity.
+     */
+    public function close(): static;
+
+    /**
+     * Reopen this entity.
+     */
+    public function reopen(): static;
+}

src/Contracts/Commentable.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\Contracts;
+
+use ConduitUI\Pr\DataTransferObjects\Comment;
+
+/**
+ * Interface for entities that can have comments.
+ *
+ * Implemented by: Issue, PullRequest, Commit, Review
+ */
+interface Commentable
+{
+    /**
+     * Get all comments on this entity.
+     *
+     * @return array<int, Comment>
+     */
+    public function comments(): array;
+
+    /**
+     * Add a comment to this entity.
+     */
+    public function comment(string $body): static;
+}

src/Contracts/Diffable.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\Contracts;
+
+use ConduitUI\Pr\DataTransferObjects\File;
+
+/**
+ * Interface for entities that have a diff (changed files).
+ *
+ * Implemented by: PullRequest, Commit
+ */
+interface Diffable
+{
+    /**
+     * Get the raw diff text.
+     */
+    public function diff(): string;
+
+    /**
+     * Get the list of changed files.
+     *
+     * @return array<int, File>
+     */
+    public function files(): array;
+}

src/Contracts/HasCommits.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\Contracts;
+
+use ConduitUI\Pr\DataTransferObjects\Commit;
+
+/**
+ * Interface for entities that have commits.
+ *
+ * Implemented by: PullRequest
+ */
+interface HasCommits
+{
+    /**
+     * Get all commits for this entity.
+     *
+     * @return array<int, Commit>
+     */
+    public function commits(): array;
+}

src/Contracts/Labelable.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\Contracts;
+
+/**
+ * Interface for entities that can have labels.
+ *
+ * Implemented by: Issue, PullRequest
+ */
+interface Labelable
+{
+    /**
+     * Add labels to this entity.
+     *
+     * @param  array<int, string>  $labels
+     */
+    public function addLabels(array $labels): static;
+
+    /**
+     * Remove a label from this entity.
+     */
+    public function removeLabel(string $label): static;
+}

src/Contracts/Mergeable.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\Contracts;
+
+/**
+ * Interface for entities that can be merged.
+ *
+ * Implemented by: PullRequest
+ */
+interface Mergeable
+{
+    /**
+     * Merge this entity.
+     *
+     * @param  string  $method  merge, squash, or rebase
+     */
+    public function merge(string $method = 'merge', ?string $title = null, ?string $message = null): static;
+}

src/Contracts/PrServiceInterface.php

@@ -11,17 +11,27 @@ interface PrServiceInterface
 {
     public function find(string $repository, int $number): PullRequest;
 
+    /**
+     * @param  array<string, mixed>  $attributes
+     */
     public function create(string $repository, array $attributes): PullRequest;
 
     public function for(string $repository): QueryBuilder;
 
     public function query(): QueryBuilder;
 
+    /**
+     * @param  array<string, mixed>  $data
+     */
     public function update(string $repository, int $number, array $data): PullRequest;
 
     public function merge(string $repository, int $number, ?string $commitMessage = null, ?string $mergeMethod = null): bool;
 
     public function close(string $repository, int $number): PullRequest;
 
+    /**
+     * @param  array<string, mixed>  $filters
+     * @return array<int, PullRequest>
+     */
     public function list(string $repository, array $filters = []): array;
 }

src/Contracts/Reviewable.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ConduitUI\Pr\Contracts;
+
+use ConduitUI\Pr\DataTransferObjects\Review;
+
+/**
+ * Interface for entities that can receive code reviews.
+ *
+ * Implemented by: PullRequest
+ */
+interface Reviewable
+{
+    /**
+     * Get all reviews for this entity.
+     *
+     * @return array<int, Review>
+     */
+    public function reviews(): array;
+
+    /**
+     * Approve this entity.
+     */
+    public function approve(?string $body = null): static;
+
+    /**
+     * Request changes on this entity.
+     */
+    public function requestChanges(string $body): static;
+
+    /**
+     * Submit a review with a specific event type.
+     *
+     * @param  string  $event  APPROVE, REQUEST_CHANGES, or COMMENT
+     * @param  array<int, array{path: string, line: int, body: string}>  $comments  Inline comments
+     */
+    public function submitReview(string $event, ?string $body = null, array $comments = []): static;
+}

src/DataTransferObjects/Base.php

@@ -13,6 +13,9 @@ public function __construct(
         public readonly Repository $repo,
     ) {}
 
+    /**
+     * @param  array{ref: string, sha: string, user: array{id: int, login: string, avatar_url: string, html_url: string, type: string}, repo: array{id: int, name: string, full_name: string, html_url: string, private: bool}}  $data
+     */
     public static function fromArray(array $data): self
     {
         return new self(
@@ -23,6 +26,9 @@ public static function fromArray(array $data): self
         );
     }
 
+    /**
+     * @return array<string, mixed>
+     */
     public function toArray(): array
     {
         return [