Block delimiter: update class to be closer to original codebase (#43683)

* Block delimiter: update class to be closer to original codebase

Since the class does not rely on WordPress, we can afford to be more permissive, and not necessarily stick to WordPress coding standards.

This reverts some of the changes made in #43648.

* Add changelog

* Update Phan baseline to avoid errors

* Update phpcs config to avoid warnings

* Ignore more rules to match original file

* Update readme to clarify coding standards

Author: jeherve

projects/packages/block-delimiter/.phan/baseline.php

@@ -8,9 +8,14 @@
  * (can be combined with --load-baseline)
  */
 return [
-    // This baseline has no suppressions
+    // # Issue statistics:
+    // PhanPossiblyUndeclaredVariable : 10+ occurrences
+    // PhanPossiblyNullTypeMismatchProperty : 7 occurrences
+    // PhanTypeMismatchArgumentInternalProbablyReal : 1 occurrence
+
     // Currently, file_suppressions and directory_suppressions are the only supported suppressions
     'file_suppressions' => [
+        'src/class-block-delimiter.php' => ['PhanPossiblyNullTypeMismatchProperty', 'PhanPossiblyUndeclaredVariable', 'PhanTypeMismatchArgumentInternalProbablyReal'],
     ],
     // 'directory_suppressions' => ['src/directory_name' => ['PhanIssueName1', 'PhanIssueName2']] can be manually added if needed.
     // (directory_suppressions will currently be ignored by subsequent calls to --save-baseline, but may be preserved in future Phan releases)

projects/packages/block-delimiter/.phpcs.dir.xml

@@ -1,24 +1,13 @@
 <?xml version="1.0"?>
 <ruleset>
-
-	<rule ref="WordPress.WP.I18n">
-		<properties>
-			<property name="text_domain" type="array">
-				<element value="jetpack-block-delimiter" />
-			</property>
-		</properties>
+	<rule ref="Jetpack-Compat-NoWP" />
+	<rule ref="Generic.CodeAnalysis.AssignmentInCondition.FoundInWhileCondition">
+		<exclude-pattern>*</exclude-pattern>
 	</rule>
-	<rule ref="Jetpack.Functions.I18n">
-		<properties>
-			<property name="text_domain" value="jetpack-block-delimiter" />
-		</properties>
+	<rule ref="Universal.Operators.DisallowStandalonePostIncrementDecrement.PostIncrementFound">
+		<exclude-pattern>*</exclude-pattern>
 	</rule>
-
-	<rule ref="WordPress.Utils.I18nTextDomainFixer">
-		<properties>
-			<property name="old_text_domain" type="array" />
-			<property name="new_text_domain" value="jetpack-block-delimiter" />
-		</properties>
+	<rule ref="Universal.Arrays.DisallowShortArraySyntax.Found">
+		<exclude-pattern>*</exclude-pattern>
 	</rule>
-
-</ruleset>
+</ruleset>

projects/packages/block-delimiter/README.md

@@ -364,6 +364,20 @@ This makes it ideal for operations like finding specific blocks, counting block
 
 You can contribute to this package by submitting a pull request to the [Jetpack repository](https://github.com/Automattic/jetpack/tree/trunk/projects/packages/block-delimiter).
 
+### Coding standards
+
+This package follows standards set by the [Jetpack Codesniffer package](https://packagist.org/packages/automattic/jetpack-codesniffer), with a few exceptions documented in the package's `.phpcs.dir.xml` file.
+
+### Testing
+
+When introducing new features or making changes to existing code, please add tests.
+
+To run the tests, you can use the following command:
+
+```bash
+composer phpunit
+```
+
 ## Using this package in your WordPress plugin
 
 If you plan on using this package in your WordPress plugin, we would recommend that you use [Jetpack Autoloader](https://packagist.org/packages/automattic/jetpack-autoloader) as your autoloader. This will allow for maximum interoperability with other plugins that use this package as well.

projects/packages/block-delimiter/changelog/update-block-delimiter-phpcs-phan-rules

@@ -0,0 +1,4 @@
+Significance: minor
+Type: changed
+
+Update phpcs and Phan configuration to be more permissive, and update main class accordingly.

projects/packages/block-delimiter/src/class-block-delimiter.php

@@ -183,18 +183,6 @@ public static function next_delimiter( string $text, int $starting_byte_offset,
 		$delimiter          = null;
 		static::$last_error = null;
 
-		// Initialize all variables that will be used later.
-		$comment_opening_at = 0;
-		$comment_closing_at = 0;
-		$namespace_at       = 0;
-		$namespace_length   = 0;
-		$name_at            = 0;
-		$name_length        = 0;
-		$json_at            = 0;
-		$json_length        = 0;
-		$has_closer         = false;
-		$has_void_flag      = false;
-
 		$close_html_comment = function ( $comment_starting_at ) use ( $text, &$at, $end ) {
 			// Find span-of-dashes comments which look like `<!----->`.
 			$span_of_dashes = strspn( $text, '-', $comment_starting_at + 2 );
@@ -218,15 +206,15 @@ public static function next_delimiter( string $text, int $starting_byte_offset,
 
 				$closer_must_be_at = $dashes_at + 2 + strspn( $text, '-', $dashes_at + 2 );
 				if ( $closer_must_be_at < $end && '!' === $text[ $closer_must_be_at ] ) {
-					++$closer_must_be_at;
+					$closer_must_be_at++;
 				}
 
 				if ( $closer_must_be_at < $end && '>' === $text[ $closer_must_be_at ] ) {
 					$at = $closer_must_be_at + 1;
 					return;
 				}
 
-				++$now_at;
+				$now_at++;
 			}
 		};
 
@@ -461,23 +449,22 @@ public static function scan_delimiters( string $text, ?string $freeform_blocks =
 		/*
 		 * Although `phpcs` confidently asserts that `$match_at` and `$match_length`
 		 * are undefined, it is not aware enough to realize that they are set by the
-		 * call to `next_delimiter` and so it's necessary to alter the code so it
-		 * doesn't get confused and reject valid code.
+		 * call to `next_delimiter` and so it’s necessary to alter the code so it
+		 * doesn’t get confused and reject valid code.
 		 */
 		$match_at     = 0;
 		$match_length = 0;
 
-		$delimiter = self::next_delimiter( $text, $at, $match_at, $match_length );
-		while ( null !== $delimiter ) {
+		while ( null !== ( $delimiter = self::next_delimiter( $text, $at, $match_at, $match_length ) ) ) {
 			// Handle top-level text as freeform blocks
 			if ( 0 === $depth && $match_at > $at && 'visit' === $freeform_blocks ) {
 				list( $text_opener, $text_closer ) = static::freeform_pair( $text, $at, $match_at - $at );
 
 				++$depth;
-				yield array( $at, 0 ) => $text_opener;
+				yield [ $at, 0 ] => $text_opener;
 
 				--$depth;
-				yield array( $match_at, 0 ) => $text_closer;
+				yield [ $match_at, 0 ] => $text_closer;
 			}
 
 			$delimiter_type = $delimiter->get_delimiter_type();
@@ -493,25 +480,24 @@ public static function scan_delimiters( string $text, ?string $freeform_blocks =
 					break;
 			}
 
-			yield array( $match_at, $match_length ) => $delimiter;
+			yield [ $match_at, $match_length ] => $delimiter;
 
 			if ( static::VOID === $delimiter_type ) {
 				--$depth;
 			}
 
-			$at        = $match_at + $match_length;
-			$delimiter = self::next_delimiter( $text, $at, $match_at, $match_length );
+			$at = $match_at + $match_length;
 		}
 
 		$end = strlen( $text );
 		if ( 'visit' === $freeform_blocks && $at < $end ) {
 			list( $text_opener, $text_closer ) = static::freeform_pair( $text, $at, $end - $at );
 
 			++$depth;
-			yield array( $at, 0 ) => $text_opener;
+			yield [ $at, 0 ] => $text_opener;
 
 			--$depth;
-			yield array( $end, 0 ) => $text_closer;
+			yield [ $end, 0 ] => $text_closer;
 		}
 	}
 
@@ -553,7 +539,7 @@ private static function freeform_pair( string $text, int $at, int $length ): arr
 		$closer->json_at      = $end_at;
 		$closer->type         = static::CLOSER;
 
-		return array( $opener, $closer );
+		return [ $opener, $closer ];
 	}
 
 	/**
@@ -567,7 +553,7 @@ public static function get_last_error() {
 	}
 
 	/**
-	 * Indicates if the last attempt to parse a block's JSON attributes failed.
+	 * Indicates if the last attempt to parse a block’s JSON attributes failed.
 	 *
 	 * @see JSON_ERROR_NONE, JSON_ERROR_DEPTH, etc…
 	 *
@@ -661,7 +647,7 @@ public function has_void_flag(): bool {
 	 * @return bool Whether this delimiter represents a block of the given type.
 	 */
 	public function is_block_type( string $block_type ): bool {
-		// This is a core/freeform text block, it's special.
+		// This is a core/freeform text block, it’s special.
 		if ( 0 === $this->name_length ) {
 			return 'core/freeform' === $block_type || 'freeform' === $block_type;
 		}
@@ -714,7 +700,7 @@ public function is_block_type( string $block_type ): bool {
 	 * @return string Fully-qualified block namespace and type, e.g. "core/paragraph".
 	 */
 	public function allocate_and_return_block_type(): string {
-		// This is a core/freeform text block, it's special.
+		// This is a core/freeform text block, it’s special.
 		if ( 0 === $this->name_length ) {
 			return 'core/freeform';
 		}
@@ -801,12 +787,7 @@ public function allocate_and_return_parsed_attributes(): ?array {
 		}
 
 		$json_span = substr( $this->source_text, $this->json_at, $this->json_length );
-		$parsed    = json_decode(
-			$json_span,
-			null, // @phan-suppress-current-line PhanTypeMismatchArgumentInternalProbablyReal -- json_decode does accept null.
-			512,
-			JSON_OBJECT_AS_ARRAY | JSON_INVALID_UTF8_SUBSTITUTE
-		);
+		$parsed    = json_decode( $json_span, null, 512, JSON_OBJECT_AS_ARRAY | JSON_INVALID_UTF8_SUBSTITUTE );
 
 		$last_error            = json_last_error();
 		$this->last_json_error = $last_error;
@@ -817,7 +798,6 @@ public function allocate_and_return_parsed_attributes(): ?array {
 	}
 
 	// Debugging methods not meant for production use.
-	// @codeCoverageIgnoreStart
 
 	/**
 	 * Prints a debugging message showing the structure of the parsed delimiter.
@@ -879,8 +859,6 @@ public function debug_print_structure(): void {
 		echo "{$c( "\e[0;36m" )}{$void_flag}{$c("\e[90m")}-->\n"; // phpcs:ignore
 	}
 
-	// @codeCoverageIgnoreEnd
-
 	// Constant declarations that would otherwise pollute the top of the class.
 
 	/**