Scaffold provider interface and test bootstrap

.gitignore

@@ -2,3 +2,6 @@
 .vscode/
 docs/
 notes/
+vendor/
+phpunit.xml
+.phpunit.result.cache

composer.json

@@ -0,0 +1,18 @@
+{
+    "name": "keithsolomon/projects-portfolio",
+    "description": "WordPress plugin — dev-only test dependencies.",
+    "type": "wordpress-plugin",
+    "require": {
+        "php": ">=7.4"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^9.6",
+        "brain/monkey": "^2.6",
+        "yoast/phpunit-polyfills": "^2.0"
+    },
+    "config": {
+        "allow-plugins": {
+            "php-http/discovery": false
+        }
+    }
+}

includes/providers/interface-repository-provider.php

@@ -0,0 +1,47 @@
+<?php
+// If this file is called directly, abort.
+if ( ! defined( 'WPINC' ) ) {
+    die;
+}
+
+/**
+ * Contract for a repository host adapter (GitHub, Gitea, ...).
+ *
+ * @since 1.1.0
+ */
+interface Repository_Provider {
+    public function get_id(): string;
+
+    public function get_label(): string;
+
+    /**
+     * Normalized repo metadata. Returns null on any failure.
+     *
+     * Shape:
+     *   [
+     *     'owner' => [ 'avatar_url' => string, 'login' => string, 'html_url' => string ],
+     *     'updated_at'         => string (ISO 8601),
+     *     'language'           => string,
+     *     'license'            => [ 'name' => string ],
+     *     'stargazers_count'   => int,
+     *     'forks_count'        => int,
+     *     'open_issues_count'  => int,
+     *   ]
+     */
+    public function get_repo_data(): ?array;
+
+    /** Direct URL to the latest release zip asset, or null. */
+    public function get_release_url(): ?string;
+
+    /** Tag name of the latest release, or 'Unknown'. */
+    public function get_latest_version(): string;
+
+    /** Public URL of the repo, for the 'View Repo' button. */
+    public function get_repo_browse_url(): string;
+
+    /**
+     * Owner profile data: [ 'avatar_url', 'login', 'html_url' ].
+     * Returns null on failure.
+     */
+    public function get_owner_data( string $owner_login ): ?array;
+}

phpunit.xml.dist

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit
+    bootstrap="tests/bootstrap.php"
+    colors="true"
+    convertErrorsToExceptions="true"
+    convertNoticesToExceptions="true"
+    convertWarningsToExceptions="true">
+    <testsuites>
+        <testsuite name="projects-portfolio">
+            <directory suffix=".php">tests</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>

tests/bootstrap.php

@@ -0,0 +1,83 @@
+<?php
+// Load Composer dev autoload (PHPUnit + Brain\Monkey + polyfills).
+$autoload = dirname( __DIR__ ) . '/vendor/autoload.php';
+if ( ! file_exists( $autoload ) ) {
+    fwrite( STDERR, "Run `composer install` before running tests.\n" );
+    exit( 1 );
+}
+require_once $autoload;
+
+// Brain\Monkey sets up minimal function stubs (apply_filters, plugin_dir_path, etc.).
+\Brain\Monkey\setUp();
+
+// Define WP constants the helpers rely on.
+if ( ! defined( 'HOUR_IN_SECONDS' ) ) {
+    define( 'HOUR_IN_SECONDS', 3600 );
+}
+if ( ! defined( 'WPINC' ) ) {
+    define( 'WPINC', 'wp-includes' );
+}
+if ( ! defined( 'ABSPATH' ) ) {
+    define( 'ABSPATH', __DIR__ . '/' );
+}
+
+// Provide minimal WordPress function stubs used by the providers under test.
+if ( ! function_exists( 'get_option' ) ) {
+    function get_option( $key, $default = false ) { return $default; }
+}
+if ( ! function_exists( 'get_transient' ) ) {
+    function get_transient( $key ) { return false; }
+}
+if ( ! function_exists( 'set_transient' ) ) {
+    function set_transient( $key, $value, $expiration ) { return true; }
+}
+if ( ! function_exists( 'delete_transient' ) ) {
+    function delete_transient( $key ) { return true; }
+}
+if ( ! function_exists( 'wp_remote_get' ) ) {
+    function wp_remote_get( $url, $args = [] ) { return new \WP_Error( 'no_http', 'no http' ); }
+}
+if ( ! function_exists( 'is_wp_error' ) ) {
+    function is_wp_error( $thing ) { return $thing instanceof \WP_Error; }
+}
+if ( ! function_exists( 'wp_remote_retrieve_response_code' ) ) {
+    function wp_remote_retrieve_response_code( $response ) {
+        if ( $response instanceof \WP_Error ) { return 0; }
+        return $response['response']['code'] ?? 0;
+    }
+}
+if ( ! function_exists( 'wp_remote_retrieve_body' ) ) {
+    function wp_remote_retrieve_body( $response ) {
+        if ( $response instanceof \WP_Error ) { return ''; }
+        return $response['body'] ?? '';
+    }
+}
+if ( ! function_exists( 'wp_remote_retrieve_header' ) ) {
+    function wp_remote_retrieve_header( $response, $header ) {
+        if ( $response instanceof \WP_Error ) { return ''; }
+        $headers = $response['headers'] ?? [];
+        $key = strtolower( $header );
+        return $headers[ $key ] ?? '';
+    }
+}
+if ( ! function_exists( 'error_log' ) ) {
+    function error_log( $message ) { /* swallow during tests */ }
+}
+
+// Minimal WP_Error stub if Brain\Monkey doesn't supply one.
+if ( ! class_exists( 'WP_Error' ) ) {
+    class WP_Error {
+        private $code;
+        private $message;
+        public function __construct( $code = '', $message = '' ) {
+            $this->code = $code;
+            $this->message = $message;
+        }
+        public function get_error_code() { return $this->code; }
+        public function get_error_message() { return $this->message; }
+    }
+}
+
+register_shutdown_function( function () {
+    \Brain\Monkey\tearDown();
+} );