feat: add content package schema validator

src/Package/ContentPackage.php

@@ -0,0 +1,98 @@
+<?php
+/**
+ * Immutable sync package value object.
+ *
+ * @package WPContentSync
+ */
+
+namespace WPContentSync\Package;
+
+final class ContentPackage {
+	public const SCHEMA_VERSION = '1.0';
+
+	/** @var array<string, mixed> */
+	private array $data;
+
+	/**
+	 * @param array<string, mixed> $data Package data.
+	 */
+	private function __construct( array $data ) {
+		$this->data = $data;
+	}
+
+	/**
+	 * @param array<string, mixed> $data Package data.
+	 */
+	public static function fromArray( array $data ): self {
+		return new self(
+			array(
+				'schema_version' => (string) ( $data['schema_version'] ?? self::SCHEMA_VERSION ),
+				'generated_at'   => (string) ( $data['generated_at'] ?? '' ),
+				'source'         => self::arrayValue( $data['source'] ?? array() ),
+				'destination'    => self::arrayValue( $data['destination'] ?? array() ),
+				'manifest'       => self::arrayValue( $data['manifest'] ?? array() ),
+				'records'        => self::arrayValue( $data['records'] ?? array() ),
+				'checksums'      => self::arrayValue( $data['checksums'] ?? array() ),
+			)
+		);
+	}
+
+	public function schemaVersion(): string {
+		return $this->data['schema_version'];
+	}
+
+	public function generatedAt(): string {
+		return $this->data['generated_at'];
+	}
+
+	/**
+	 * @return array<string, mixed>
+	 */
+	public function source(): array {
+		return $this->data['source'];
+	}
+
+	/**
+	 * @return array<string, mixed>
+	 */
+	public function destination(): array {
+		return $this->data['destination'];
+	}
+
+	/**
+	 * @return array<string, mixed>
+	 */
+	public function manifest(): array {
+		return $this->data['manifest'];
+	}
+
+	/**
+	 * @return array<string, mixed>
+	 */
+	public function records(): array {
+		return $this->data['records'];
+	}
+
+	/**
+	 * @return array<string, mixed>
+	 */
+	public function checksums(): array {
+		return $this->data['checksums'];
+	}
+
+	/**
+	 * @return array<string, mixed>
+	 */
+	public function toArray(): array {
+		return $this->data;
+	}
+
+	/**
+	 * @param mixed $value Value to normalize.
+	 *
+	 * @return array<string, mixed>
+	 */
+	private static function arrayValue( $value ): array {
+		return is_array( $value ) ? $value : array();
+	}
+}

src/Package/PackageValidationResult.php

@@ -0,0 +1,42 @@
+<?php
+/**
+ * Package validation result.
+ *
+ * @package WPContentSync
+ */
+
+namespace WPContentSync\Package;
+
+final class PackageValidationResult {
+	/** @var array<int, string> */
+	private array $errors;
+
+	/**
+	 * @param array<int, string> $errors Validation errors.
+	 */
+	private function __construct( array $errors ) {
+		$this->errors = array_values( $errors );
+	}
+
+	public static function valid(): self {
+		return new self( array() );
+	}
+
+	/**
+	 * @param array<int, string> $errors Validation errors.
+	 */
+	public static function invalid( array $errors ): self {
+		return new self( $errors );
+	}
+
+	public function isValid(): bool {
+		return array() === $this->errors;
+	}
+
+	/**
+	 * @return array<int, string>
+	 */
+	public function errors(): array {
+		return $this->errors;
+	}
+}

src/Package/PackageValidator.php

@@ -0,0 +1,88 @@
+<?php
+/**
+ * Versioned package schema validator.
+ *
+ * @package WPContentSync
+ */
+
+namespace WPContentSync\Package;
+
+final class PackageValidator {
+	private const RECORD_BUCKETS = array(
+		'posts',
+		'terms',
+		'media',
+		'custom_post_types',
+	);
+
+	/**
+	 * @param array<string, mixed> $data Decoded package data.
+	 */
+	public function validate( array $data ): PackageValidationResult {
+		$errors = array();
+
+		foreach ( array( 'schema_version', 'generated_at', 'source', 'destination', 'manifest', 'records', 'checksums' ) as $field ) {
+			if ( ! array_key_exists( $field, $data ) ) {
+				$errors[] = $field . ' is required.';
+			}
+		}
+
+		if ( isset( $data['schema_version'] ) && ContentPackage::SCHEMA_VERSION !== $data['schema_version'] ) {
+			$errors[] = 'schema_version must be ' . ContentPackage::SCHEMA_VERSION . '.';
+		}
+
+		if ( isset( $data['source'] ) && ! is_array( $data['source'] ) ) {
+			$errors[] = 'source must be an object.';
+		}
+
+		if ( isset( $data['destination'] ) && ! is_array( $data['destination'] ) ) {
+			$errors[] = 'destination must be an object.';
+		}
+
+		if ( isset( $data['manifest'] ) && ! is_array( $data['manifest'] ) ) {
+			$errors[] = 'manifest must be an object.';
+		}
+
+		if ( isset( $data['records'] ) && ! is_array( $data['records'] ) ) {
+			$errors[] = 'records must be an object.';
+		}
+
+		if ( isset( $data['checksums'] ) && ! is_array( $data['checksums'] ) ) {
+			$errors[] = 'checksums must be an object.';
+		}
+
+		if ( isset( $data['manifest'], $data['records'] ) && is_array( $data['manifest'] ) && is_array( $data['records'] ) ) {
+			$errors = array_merge( $errors, $this->validateRecordBuckets( $data['manifest'], $data['records'] ) );
+		}
+
+		return array() === $errors ? PackageValidationResult::valid() : PackageValidationResult::invalid( $errors );
+	}
+
+	/**
+	 * @param array<string, mixed> $manifest Package manifest.
+	 * @param array<string, mixed> $records  Package records.
+	 *
+	 * @return array<int, string>
+	 */
+	private function validateRecordBuckets( array $manifest, array $records ): array {
+		$errors = array();
+
+		foreach ( self::RECORD_BUCKETS as $bucket ) {
+			if ( ! isset( $records[ $bucket ] ) || ! is_array( $records[ $bucket ] ) ) {
+				$errors[] = 'records.' . $bucket . ' is required and must be an array.';
+				continue;
+			}
+
+			if ( ! isset( $manifest[ $bucket ] ) || ! is_int( $manifest[ $bucket ] ) ) {
+				$errors[] = 'manifest.' . $bucket . ' is required and must be an integer.';
+				continue;
+			}
+
+			if ( count( $records[ $bucket ] ) !== $manifest[ $bucket ] ) {
+				$errors[] = 'manifest.' . $bucket . ' must match records.' . $bucket . ' count.';
+			}
+		}
+
+		return $errors;
+	}
+}

tests/Unit/Package/ContentPackageTest.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace WPContentSync\Tests\Unit\Package;
+
+use PHPUnit\Framework\TestCase;
+use WPContentSync\Package\ContentPackage;
+
+class ContentPackageTest extends TestCase {
+	public function test_it_normalizes_package_arrays(): void {
+		$package = ContentPackage::fromArray(
+			array(
+				'schema_version' => '1.0',
+				'generated_at'   => '2026-04-26T20:30:00+00:00',
+				'source'         => array(
+					'site_url' => 'https://example.test',
+					'name'     => 'Example Production',
+				),
+				'destination'    => array(
+					'site_url' => 'https://staging.example.test',
+					'name'     => 'Example Staging',
+				),
+				'manifest'       => array(
+					'posts'             => 1,
+					'terms'             => 0,
+					'media'             => 0,
+					'custom_post_types' => 0,
+				),
+				'records'        => array(
+					'posts'             => array(
+						array(
+							'id'   => 123,
+							'type' => 'post',
+						),
+					),
+					'terms'             => array(),
+					'media'             => array(),
+					'custom_post_types' => array(),
+				),
+				'checksums'      => array(
+					'records' => 'sha256:abc123',
+				),
+			)
+		);
+
+		self::assertSame( '1.0', $package->schemaVersion() );
+		self::assertSame( '2026-04-26T20:30:00+00:00', $package->generatedAt() );
+		self::assertSame( 'https://example.test', $package->source()['site_url'] );
+		self::assertSame( 'https://staging.example.test', $package->destination()['site_url'] );
+		self::assertSame( 1, $package->manifest()['posts'] );
+		self::assertSame( 123, $package->records()['posts'][0]['id'] );
+		self::assertSame( 'sha256:abc123', $package->checksums()['records'] );
+		self::assertSame( $package->toArray(), ContentPackage::fromArray( $package->toArray() )->toArray() );
+	}
+}

tests/Unit/Package/PackageValidatorTest.php

@@ -0,0 +1,93 @@
+<?php
+
+namespace WPContentSync\Tests\Unit\Package;
+
+use PHPUnit\Framework\TestCase;
+use WPContentSync\Package\PackageValidator;
+
+class PackageValidatorTest extends TestCase {
+	public function test_it_accepts_valid_packages(): void {
+		$result = ( new PackageValidator() )->validate( $this->validPackage() );
+
+		self::assertTrue( $result->isValid() );
+		self::assertSame( array(), $result->errors() );
+	}
+
+	public function test_it_rejects_missing_required_fields(): void {
+		$package = $this->validPackage();
+		unset( $package['records'] );
+
+		$result = ( new PackageValidator() )->validate( $package );
+
+		self::assertFalse( $result->isValid() );
+		self::assertSame( array( 'records is required.' ), $result->errors() );
+	}
+
+	public function test_it_rejects_unsupported_schema_versions(): void {
+		$package                   = $this->validPackage();
+		$package['schema_version'] = '2.0';
+
+		$result = ( new PackageValidator() )->validate( $package );
+
+		self::assertFalse( $result->isValid() );
+		self::assertSame( array( 'schema_version must be 1.0.' ), $result->errors() );
+	}
+
+	public function test_it_rejects_missing_record_buckets(): void {
+		$package = $this->validPackage();
+		unset( $package['records']['media'] );
+
+		$result = ( new PackageValidator() )->validate( $package );
+
+		self::assertFalse( $result->isValid() );
+		self::assertSame( array( 'records.media is required and must be an array.' ), $result->errors() );
+	}
+
+	public function test_it_rejects_manifest_counts_that_do_not_match_records(): void {
+		$package                      = $this->validPackage();
+		$package['manifest']['posts'] = 2;
+
+		$result = ( new PackageValidator() )->validate( $package );
+
+		self::assertFalse( $result->isValid() );
+		self::assertSame( array( 'manifest.posts must match records.posts count.' ), $result->errors() );
+	}
+
+	/**
+	 * @return array<string, mixed>
+	 */
+	private function validPackage(): array {
+		return array(
+			'schema_version' => '1.0',
+			'generated_at'   => '2026-04-26T20:30:00+00:00',
+			'source'         => array(
+				'site_url' => 'https://example.test',
+				'name'     => 'Example Production',
+			),
+			'destination'    => array(
+				'site_url' => 'https://staging.example.test',
+				'name'     => 'Example Staging',
+			),
+			'manifest'       => array(
+				'posts'             => 1,
+				'terms'             => 0,
+				'media'             => 0,
+				'custom_post_types' => 0,
+			),
+			'records'        => array(
+				'posts'             => array(
+					array(
+						'id'   => 123,
+						'type' => 'post',
+					),
+				),
+				'terms'             => array(),
+				'media'             => array(),
+				'custom_post_types' => array(),
+			),
+			'checksums'      => array(
+				'records' => 'sha256:abc123',
+			),
+		);
+	}
+}