Merge pull request 'docs: add url transformer implementation plan' (#1) from feature/url-transformer-plan into main

Reviewed-on: #1

docs/superpowers/plans/2026-04-26-wordpress-content-sync-implementation-roadmap.md

@@ -37,7 +37,7 @@ Adds domain mapping, URL replacement in post content, URL replacement inside ser
 
 ## Phase 3: Content Package Schema and File Transport
 
-**Plan:** `docs/superpowers/plans/2026-04-26-wordpress-content-sync-file-transport.md`
+**Plan to create after Phase 2:** `docs/superpowers/plans/2026-04-26-wordpress-content-sync-file-transport.md`
 
 Defines the sync package schema and implements export/import through JSON files for posts, pages, taxonomies, media metadata, and custom post type records.
 

src/Package/ContentPackage.php

@@ -1,98 +0,0 @@
-<?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

@@ -1,42 +0,0 @@
-<?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

@@ -1,88 +0,0 @@
-<?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

@@ -1,54 +0,0 @@
-<?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

@@ -1,93 +0,0 @@
-<?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',
-			),
-		);
-	}
-}