Fix phpcs formatting (#17)

Author: alecgeatches

.prettierignore

@@ -3,6 +3,7 @@
 build
 vendor
 package-lock.json
+composer.lock
 
 # Pinned Gutenberg subtree — formatted by its own tooling at the pin.
 gutenberg
@@ -14,5 +15,11 @@ src/engines/intent-log
 # Vendored third-party code from the Yjs ecosystem.
 src/engines/yjs/y-utilities
 
+# Vendored y-php and automerge-php libraries (imported verbatim; they
+# carry their own style and configs, and must stay byte-identical to
+# their upstream pins).
+includes/lib/y-php
+includes/lib/automerge-php
+
 # Playwright e2e output.
 artifacts

gutenberg-sync-engines.php

@@ -39,16 +39,16 @@
 
 require_once GUTENBERG_SYNC_ENGINES_PATH . 'includes/class-gutenberg-sync-engines-plugin.php';
 
-/**
- * Boots the plugin once all plugins are loaded, so the collaborative-editing
- * framework (shipped in Gutenberg / WordPress core) is already available to
- * feature-detect.
- *
- * @since 0.1.0
- *
- * @return void
- */
 if ( ! function_exists( 'gutenberg_sync_engines_bootstrap' ) ) {
+	/**
+	 * Boots the plugin once all plugins are loaded, so the collaborative-editing
+	 * framework (shipped in Gutenberg / WordPress core) is already available to
+	 * feature-detect.
+	 *
+	 * @since 0.1.0
+	 *
+	 * @return void
+	 */
 	function gutenberg_sync_engines_bootstrap() {
 		Gutenberg_Sync_Engines_Plugin::instance()->boot();
 	}

includes/engines/de-rtc/class-wp-de-rtc-engine.php

@@ -406,6 +406,7 @@ private function resolve_base_content( array $state, string $base_version ) {
 				: array();
 			$snapshot  = $snapshots[ $base_version ] ?? null;
 			if ( is_array( $snapshot ) && is_string( $snapshot['content_base64'] ?? null ) ) {
+				// phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_decode -- Decodes a stored version snapshot's content.
 				$decoded = base64_decode( $snapshot['content_base64'], true );
 				if ( false !== $decoded ) {
 					return $decoded;

includes/engines/intent-log/class-wp-intent-log-document.php

@@ -326,9 +326,17 @@ private static function canonical_block( array $block ): array {
 				usort(
 					$formats,
 					static function ( $a, $b ) {
-						return ( $a['start'] <=> $b['start'] )
-							?: ( $a['end'] <=> $b['end'] )
-							?: strcmp( $a['format'], $b['format'] );
+						$order = $a['start'] <=> $b['start'];
+
+						if ( 0 === $order ) {
+							$order = $a['end'] <=> $b['end'];
+						}
+
+						if ( 0 === $order ) {
+							$order = strcmp( $a['format'], $b['format'] );
+						}
+
+						return $order;
 					}
 				);
 				$fields[ $name ] = array(

includes/engines/intent-log/class-wp-intent-log-engine.php

@@ -131,6 +131,7 @@ class WP_Intent_Log_Engine implements WP_Sync_Engine {
 		 * Storage backend.
 		 *
 		 * @since 7.2.0
+		 * @var WP_Sync_Storage
 		 */
 		private WP_Sync_Storage $storage;
 
@@ -314,6 +315,7 @@ public function handle_updates( string $room, int $client_id, int $cursor, array
 			$lock         = $this->acquire_room_lock( $room );
 			$lock_wait_ms = round( ( microtime( true ) - $lock_started ) * 1000, 1 );
 			if ( is_wp_error( $lock ) ) {
+				// phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores, WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Query Monitor's debug hook.
 				do_action( 'qm/debug', "wp-sync: ingest lock timeout for {$room} after {$lock_wait_ms}ms" );
 				return $lock;
 			}
@@ -377,6 +379,7 @@ private function handle_updates_locked( string $room, int $client_id, array $upd
 				$intent_id = is_array( $intent ) && is_string( $intent['intentId'] ?? null ) && '' !== $intent['intentId']
 					? $intent['intentId']
 					: null;
+
 				/*
 				 * Malformed rows settle PER-INTENT as `invalid-payload`
 				 * voids instead of failing the whole request: a request-
@@ -412,6 +415,7 @@ private function handle_updates_locked( string $room, int $client_id, array $upd
 				$submitted_ids[]   = $intent_id;
 			}
 			if ( count( $invalid ) > 0 ) {
+				// phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores, WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Query Monitor's debug hook.
 				do_action( 'qm/debug', 'wp-sync: ' . count( $invalid ) . " invalid intent(s) voided in {$room}" );
 			}
 
@@ -622,12 +626,15 @@ function ( $intent ) use ( $state, $base_seq, &$seen_in_batch, &$stale ) {
 			$plan_counts['stale']    = count( $stale );
 			$plan_counts['approval'] = array_sum( array_map( 'count', $requires_approval ) );
 			if ( $plan_counts['escalated'] > 0 ) {
+				// phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores, WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Query Monitor's debug hook.
 				do_action( 'qm/debug', "wp-sync: {$plan_counts['escalated']} intent(s) escalated for review in {$room}" );
 			}
 			if ( $plan_counts['approval'] > 0 ) {
+				// phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores, WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Query Monitor's debug hook.
 				do_action( 'qm/debug', "wp-sync: {$plan_counts['approval']} intent(s) parked for approval in {$room} (author lacks unfiltered_html)" );
 			}
 			if ( $plan_counts['stale'] > 0 ) {
+				// phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores, WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Query Monitor's debug hook.
 				do_action( 'qm/debug', "wp-sync: {$plan_counts['stale']} stale-base intent(s) voided in {$room} (client below retention horizon)" );
 			}
 			if ( ! empty( $context['debug'] ) ) {
@@ -823,6 +830,19 @@ private static function attr_value_requires_unfiltered_html( $value ): bool {
 			return false;
 		}
 
+		/**
+		 * Whether a block spec carries markup its author may not publish
+		 * without `unfiltered_html`.
+		 *
+		 * Judges the `_wrapper` internal attr, every other attr's string
+		 * leaves, the block-level and per-field format spans, and recurses
+		 * into child block specs.
+		 *
+		 * @since 7.2.0
+		 *
+		 * @param array $block Block spec (make_block() shape).
+		 * @return bool True when the spec requires `unfiltered_html`.
+		 */
 		private static function block_spec_requires_unfiltered_html( array $block ): bool {
 			/*
 			 * Attributes: the _wrapper internal attr re-emits as raw markup
@@ -1032,6 +1052,7 @@ private function maybe_checkpoint( string $room, int $client_id, int $window_int
 			if ( $cursor <= 0 ) {
 				return true;
 			}
+			// phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores, WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Query Monitor's debug hook.
 			do_action( 'qm/debug', "wp-sync: checkpoint at seq {$head_seq} for {$room}" );
 			$this->storage->set_room_meta(
 				$room,
@@ -1048,6 +1069,7 @@ private function maybe_checkpoint( string $room, int $client_id, int $window_int
 				// record the floor for the read path.
 				$this->storage->remove_updates_before_cursor( $room, (int) $previous['cursor'] );
 				$this->storage->set_room_meta( $room, 'intent_log_floor', (int) $previous['cursor'] );
+				// phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores, WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Query Monitor's debug hook.
 				do_action( 'qm/debug', "wp-sync: trimmed history below cursor {$previous['cursor']} for {$room}" );
 			}
 			return true;

includes/engines/intent-log/class-wp-intent-log-planner.php

@@ -12,7 +12,7 @@
 	 * `src/engines/intent-log/rebase.js` (and `sync-id.js` for genesis
 	 * identity).
 	 *
-	 * plan_batch() is THE shared deterministic core: a pure function of
+	 * The plan_batch() method is THE shared deterministic core: a pure function of
 	 * (units, log, doc-at) that decides, for one client's batch, which
 	 * intents apply (with transformed payloads), which escalate to the
 	 * proposal lane, and which void. The server commits a plan at ingest; a
@@ -64,6 +64,7 @@ public static function genesis_sync_id( int $post_id, int $revision_id, array $p
 			$input  = $post_id . ':' . $revision_id . ':' . implode( '.', $path );
 			$digest = substr( hash( 'sha256', $input, true ), 0, 16 );
 
+			// phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_encode -- Derives the base64url syncId from a binary digest.
 			return rtrim( strtr( base64_encode( $digest ), '+/', '-_' ), '=' );
 		}
 
@@ -240,6 +241,7 @@ public static function is_valid_payload( string $type, array $payload ): bool {
 			$is_any             = static function (): bool {
 				return true;
 			};
+
 			/*
 			 * Block names materialize into comment delimiters UNESCAPED
 			 * (serialize_block escapes attrs, not the name), so a name
@@ -923,9 +925,10 @@ private static function rebase_intent( array $intent, array $priors, array $doc_
 		 *
 		 * @since 7.2.0
 		 *
-		 * @param array    $units  Batch grouped into units (group_units).
-		 * @param array    $log    Accepted log (batch's intents NOT included).
-		 * @param callable $doc_at fn( int $seq ): array document at that log position.
+		 * @param array    $units     Batch grouped into units (group_units).
+		 * @param array    $log       Accepted log (batch's intents NOT included).
+		 * @param callable $doc_at    fn( int $seq ): array document at that log position.
+		 * @param int      $first_seq Sequence number of the first entry in $log (0 for a full log).
 		 * @return array array( 'rows' => row[], 'headDoc' => array ). Each row:
 		 *               array( 'intent', 'disposition', 'accepted' => ?array, 'proposal' => ?array ).
 		 */

includes/engines/intent-log/class-wp-intent-log-rich-text.php

@@ -145,11 +145,11 @@ private static function json( array $value ): string {
 		private static function decode_entities( string $raw ): string {
 			return preg_replace_callback(
 				'/&([a-zA-Z]+|#x?[0-9a-fA-F]+);?/',
-				static function ( $match ) {
-					if ( ';' !== substr( $match[0], -1 ) ) {
-						return $match[0];
+				static function ( $matches ) {
+					if ( ';' !== substr( $matches[0], -1 ) ) {
+						return $matches[0];
 					}
-					$body = $match[1];
+					$body = $matches[1];
 					if ( '#' === $body[0] ) {
 						$code = ( 'x' === $body[1] || 'X' === $body[1] )
 							? intval( substr( $body, 2 ), 16 )
@@ -373,9 +373,17 @@ private static function parse_strict( string $html ): array {
 			usort(
 				$formats,
 				static function ( $a, $b ) {
-					return ( $a['start'] <=> $b['start'] )
-						?: ( $a['end'] <=> $b['end'] )
-						?: strcmp( $a['format'], $b['format'] );
+					$order = $a['start'] <=> $b['start'];
+
+					if ( 0 === $order ) {
+						$order = $a['end'] <=> $b['end'];
+					}
+
+					if ( 0 === $order ) {
+						$order = strcmp( $a['format'], $b['format'] );
+					}
+
+					return $order;
 				}
 			);
 
@@ -409,9 +417,17 @@ public static function field_to_html( array $field ): string {
 			usort(
 				$format_spans,
 				static function ( $a, $b ) {
-					return ( $a['start'] <=> $b['start'] )
-						?: ( $b['end'] <=> $a['end'] )
-						?: strcmp( $a['format'], $b['format'] );
+					$order = $a['start'] <=> $b['start'];
+
+					if ( 0 === $order ) {
+						$order = $b['end'] <=> $a['end'];
+					}
+
+					if ( 0 === $order ) {
+						$order = strcmp( $a['format'], $b['format'] );
+					}
+
+					return $order;
 				}
 			);
 
@@ -457,7 +473,7 @@ static function ( $a, $b ) {
 			while ( true ) {
 				// Close spans ending here (with close/reopen stack repair).
 				$reopen = array();
-				while ( count( $stack ) > 0 ) {
+				while ( array() !== $stack ) {
 					$has_ender = false;
 					foreach ( $stack as $span ) {
 						if ( $span['end'] === $position ) {
@@ -508,5 +524,5 @@ static function ( $a, $b ) {
 	 * @since 7.2.0
 	 * @access private
 	 */
-	class WP_Intent_Log_Unsupported_Html extends Exception {}
+	class WP_Intent_Log_Unsupported_Html extends Exception {} // phpcs:ignore Generic.Files.OneObjectStructurePerFile.MultipleFound -- Internal signal exception, colocated with its only thrower.
 }

includes/engines/yjs-server/class-wp-yjs-server-engine.php

@@ -156,6 +156,7 @@ class WP_Yjs_Server_Engine implements WP_Sync_Engine {
 		 * Storage backend.
 		 *
 		 * @since 0.2.0
+		 * @var WP_Sync_Storage
 		 */
 		private WP_Sync_Storage $storage;
 
@@ -289,6 +290,7 @@ public function handle_updates( string $room, int $client_id, int $cursor, array
 					);
 				}
 
+				// phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_decode -- Decodes the client's binary CRDT update from the wire format.
 				$binary = base64_decode( (string) $update['data'], true );
 				if ( false === $binary || '' === $binary ) {
 					$dispositions[] = array(
@@ -317,6 +319,7 @@ public function handle_updates( string $room, int $client_id, int $cursor, array
 				$this->room_docs[ $room ] = null;
 
 				if ( ! self::is_decodable( $buffer ) ) {
+					// phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores, WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Query Monitor's debug hook.
 					do_action( 'qm/debug', "wp-sync: yjs-server rejected a malformed update in {$room}" );
 					$dispositions[] = array(
 						'status' => 'voided',
@@ -348,6 +351,7 @@ public function handle_updates( string $room, int $client_id, int $cursor, array
 
 				$diff = self::apply_update_for_row( $doc, $buffer );
 				if ( null !== $diff ) {
+					// phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores, WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Query Monitor's debug hook.
 					do_action( 'qm/debug', "wp-sync: yjs-server repaired {$room} from the update log during ingest" );
 					$diffs[ count( $dispositions ) ] = $diff;
 					$dispositions[]                  = array( 'status' => 'applied' );
@@ -362,6 +366,7 @@ public function handle_updates( string $room, int $client_id, int $cursor, array
 				 */
 				$doc                      = self::rebuild_doc( $before_bytes, $diffs );
 				$this->room_docs[ $room ] = null;
+				// phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores, WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Query Monitor's debug hook.
 				do_action( 'qm/debug', "wp-sync: yjs-server update depends on items missing from {$room}; client must resync" );
 				$dispositions[] = array(
 					'status' => 'voided',
@@ -375,6 +380,7 @@ public function handle_updates( string $room, int $client_id, int $cursor, array
 				// voids and leave the row log untouched. A replay-repaired
 				// canonical is still worth persisting.
 				if ( $replayed ) {
+					// phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_encode -- Encodes the canonical document's binary bytes for storage.
 					$this->save_canonical( $room, $doc, $load_cursor, base64_encode( $after_bytes ) );
 				}
 				foreach ( $dispositions as $i => $disposition ) {
@@ -411,6 +417,7 @@ public function handle_updates( string $room, int $client_id, int $cursor, array
 
 			// $after_bytes IS the canonical encoding at the new head; reuse
 			// it rather than encoding the document a third time.
+			// phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_encode -- Encodes the canonical document's binary bytes for storage.
 			$this->save_canonical( $room, $doc, $load_cursor, base64_encode( $after_bytes ) );
 			$this->maybe_checkpoint( $room, $client_id, $doc );
 
@@ -550,6 +557,7 @@ private function load_room( string $room ) {
 					// replay below.
 					$doc         = new \Yjs\Utils\Doc();
 					$meta_cursor = 0;
+					// phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores, WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Query Monitor's debug hook.
 					do_action( 'qm/debug', "wp-sync: yjs-server canonical snapshot corrupt for {$room}; replaying log" );
 				}
 			}
@@ -617,6 +625,7 @@ private static function apply_rows_to_doc( \Yjs\Utils\Doc $doc, array $rows, str
 					}
 				} catch ( \Throwable $e ) {
 					$clean = false;
+					// phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores, WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Query Monitor's debug hook.
 					do_action( 'qm/debug', "wp-sync: yjs-server skipped a stored row that did not apply in {$room}" );
 				}
 			}
@@ -848,12 +857,14 @@ private function maybe_checkpoint( string $room, int $client_id, \Yjs\Utils\Doc
 			if ( $cursor <= 0 ) {
 				return true;
 			}
+			// phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores, WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Query Monitor's debug hook.
 			do_action( 'qm/debug', "wp-sync: yjs-server checkpoint for {$room}" );
 			$this->storage->set_room_meta( $room, self::META_CHECKPOINT, array( 'cursor' => $cursor ) );
 
 			if ( $prev_cursor > 0 ) {
 				$this->storage->remove_updates_before_cursor( $room, $prev_cursor );
 				$this->storage->set_room_meta( $room, self::META_FLOOR, $prev_cursor );
+				// phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores, WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Query Monitor's debug hook.
 				do_action( 'qm/debug', "wp-sync: yjs-server trimmed history below cursor {$prev_cursor} for {$room}" );
 			}
 
@@ -875,6 +886,7 @@ private function maybe_checkpoint( string $room, int $client_id, \Yjs\Utils\Doc
 		 * @return true|WP_Error True on success.
 		 */
 		private function initialize_room( string $room, \Yjs\Utils\Doc $doc ) {
+			// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase -- clientID is the y-php Doc property, mirroring JS Yjs naming.
 			$doc->clientID = self::GENESIS_CLIENT_ID;
 
 			$post     = null;

includes/lib/y-php-loader.php

@@ -2,7 +2,7 @@
 /**
  * Runtime loader for the vendored y-php library.
  *
- * y-php ships Composer metadata, but the plugin cannot assume a Composer
+ * The y-php library ships Composer metadata, but the plugin cannot assume a Composer
  * autoloader at runtime, so this shim provides the equivalent wiring:
  * a PSR-4 autoloader for the `Yjs\` namespace plus the two eager files
  * Composer's `files` directive would load (namespace functions and