Block API: Refactor parser module in preparation for future work.

This patch contains a mixture of small refators, mostly a combination of
updating comments and explanations as well as rearranging some array
iterating code to use more traditional loop control structures.

While the comments should be self-explanatory, the loop control
structures are refactored for a dual purpose. In framework code like
this that is core to the project and often untouched, there is value in
optimizing to eliminate memory allocations and reduce pressure on the
garbage collector. These costs are often difficult to profile in
existing tools. More imporantly, as we think about introducing an
asynchronous block loading system we need to prepare to handle the
semantic changes that asynchronous flow introduces.

These changes are meant to smooth the transition to asynchronous code
while clarifying how blocks are loaded into the editor.

packages/blocks/README.md

@@ -614,7 +614,7 @@ _Parameters_
 
 _Returns_
 
--   `Array`: Block list.
+-   `WPBlock[]`: Block list.
 
 ### parseWithAttributeSchema
 

packages/blocks/src/api/parser/apply-block-deprecated-versions.js

@@ -22,7 +22,7 @@ function stubFalse() {
  * and no eligible migrations exist.
  *
  * @param {import(".").WPBlock}                   block     Parsed and invalid block object.
- * @param {import(".").WPRawBlock}                rawBlock  Raw block object.
+ * @param {import(".").BlockNode}                 rawBlock  Raw block object.
  * @param {import('../registration').WPBlockType} blockType Block type. This is normalize not necessary and
  *                                                          can be inferred from the block name,
  *                                                          but it's here for performance reasons.

packages/blocks/src/api/parser/convert-legacy-block.js

@@ -3,29 +3,28 @@
  * both in the parser level for previous content and to convert such blocks
  * used in Custom Post Types templates.
  *
- * @param {string} name       The block's name
- * @param {Object} attributes The block's attributes
+ * @param {string|null} name       The block's name
+ * @param {Object|null} attributes The block's attributes
  *
- * @return {[string, Object]} The block's name and attributes, changed accordingly if a match was found
+ * @return {[string, Object|null]} The block's name and attributes, changed accordingly if a match was found
  */
 export function convertLegacyBlockNameAndAttributes( name, attributes ) {
-	const newAttributes = { ...attributes };
 	// Convert 'core/cover-image' block in existing content to 'core/cover'.
 	if ( 'core/cover-image' === name ) {
-		name = 'core/cover';
+		return [ 'core/cover', attributes ];
 	}
 
 	// Convert 'core/text' blocks in existing content to 'core/paragraph'.
 	if ( 'core/text' === name || 'core/cover-text' === name ) {
-		name = 'core/paragraph';
+		return [ 'core/paragraph', attributes ];
 	}
 
 	// Convert derivative blocks such as 'core/social-link-wordpress' to the
 	// canonical form 'core/social-link'.
 	if ( name && name.indexOf( 'core/social-link-' ) === 0 ) {
 		// Capture `social-link-wordpress` into `{"service":"wordpress"}`
-		newAttributes.service = name.substring( 17 );
-		name = 'core/social-link';
+		const service = name.substring( 17 );
+		return [ 'core/social-link', { ...attributes, service } ];
 	}
 
 	// Convert derivative blocks such as 'core-embed/instagram' to the
@@ -37,45 +36,53 @@ export function convertLegacyBlockNameAndAttributes( name, attributes ) {
 			speaker: 'speaker-deck',
 			polldaddy: 'crowdsignal',
 		};
+
+		const newAttributes = {};
+
 		newAttributes.providerNameSlug =
 			providerSlug in deprecated
 				? deprecated[ providerSlug ]
 				: providerSlug;
+
 		// This is needed as the `responsive` attribute was passed
 		// in a different way before the refactoring to block variations.
 		if ( ! [ 'amazon-kindle', 'wordpress' ].includes( providerSlug ) ) {
 			newAttributes.responsive = true;
 		}
-		name = 'core/embed';
+
+		return [ 'core/embed', { ...attributes, ...newAttributes } ];
 	}
 
 	// Convert Post Comment blocks in existing content to Comment blocks.
 	// TODO: Remove these checks when WordPress 6.0 is released.
 	if ( name === 'core/post-comment-author' ) {
-		name = 'core/comment-author-name';
+		return [ 'core/comment-author-name', attributes ];
 	}
 	if ( name === 'core/post-comment-content' ) {
-		name = 'core/comment-content';
+		return [ 'core/comment-content', attributes ];
 	}
 	if ( name === 'core/post-comment-date' ) {
-		name = 'core/comment-date';
+		return [ 'core/comment-date', attributes ];
 	}
 	if ( name === 'core/comments-query-loop' ) {
-		name = 'core/comments';
-		const { className = '' } = newAttributes;
-		if ( ! className.includes( 'wp-block-comments-query-loop' ) ) {
-			newAttributes.className = [
-				'wp-block-comments-query-loop',
-				className,
-			].join( ' ' );
-		}
+		const { className = '' } = attributes;
+		const needsClassName = ! className.includes(
+			'wp-block-comments-query-loop'
+		);
+		const newAttributes = needsClassName
+			? {
+					...attributes,
+					className: `wp-block-comments-query-loop ${ className }`,
+			  }
+			: attributes;
+
 		// Note that we also had to add a deprecation to the block in order
 		// for the ID change to work.
+		return [ 'core/comments', newAttributes ];
 	}
 	if ( name === 'core/post-comments' ) {
-		name = 'core/comments';
-		newAttributes.legacy = true;
+		return [ 'core/comments', { ...attributes, legacy: true } ];
 	}
 
-	return [ name, newAttributes ];
+	return [ name, attributes ];
 }