Fix multi-line parameter description indentation in README generation (#285)

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Author: Copilot

features/scaffold-package-readme.feature

@@ -437,5 +437,89 @@ Feature: Scaffold a README.md file for an existing package
 
     When I run `wp --require=foo/command.php scaffold package-readme foo`
     Then the foo/README.md file should exist
-    And the contents of the foo/README.md file should match /\t\t.*Read content from/
-    And the contents of the foo/README.md file should match /\t\t.*Passing/
+    And the contents of the foo/README.md file should match /\t\tRead content from/
+    And the contents of the foo/README.md file should match /\t\tPassing/
+
+  Scenario: README correctly indents continuation paragraphs with zero leading spaces
+    Given an empty directory
+    And a foo/command.php file:
+      """
+      <?php
+      /**
+       * Zero-space continuation test command.
+       */
+      class Zero_Space_Test_Command {
+          /**
+           * Test command where continuation paragraph has no leading spaces.
+           *
+           * ## OPTIONS
+           *
+           * [--extra]
+           * : Show extended version information.
+           *
+           * Note: to retrieve the database revision for an individual subsite,
+           * use `wp option get db_version --url=<subsite>`.
+           *
+           * @when before_wp_load
+           */
+          public function __invoke( $args, $assoc_args ) {}
+      }
+      WP_CLI::add_command( 'zero-space-test', 'Zero_Space_Test_Command' );
+      """
+    And a foo/composer.json file:
+      """
+      {
+          "name": "wp-cli/zero-space-test",
+          "description": "Test",
+          "extra": {
+              "commands": ["zero-space-test"]
+          }
+      }
+      """
+
+    When I run `wp --require=foo/command.php scaffold package-readme foo`
+    Then the foo/README.md file should exist
+    And the contents of the foo/README.md file should match /\t\tShow extended version information/
+    And the contents of the foo/README.md file should match /\t\tNote: to retrieve/
+
+  Scenario: README correctly indents continuation paragraphs with one leading space
+    Given an empty directory
+    And a foo/command.php file:
+      """
+      <?php
+      /**
+       * One-space continuation test command.
+       */
+      class One_Space_Test_Command {
+          /**
+           * Test command where continuation paragraph has one leading space.
+           *
+           * ## OPTIONS
+           *
+           * [--extra]
+           * : Show extended version information.
+           *
+           *  Note: to retrieve the database revision for an individual subsite,
+           *  use `wp option get db_version --url=<subsite>`.
+           *
+           * @when before_wp_load
+           */
+          public function __invoke( $args, $assoc_args ) {}
+      }
+      WP_CLI::add_command( 'one-space-test', 'One_Space_Test_Command' );
+      """
+    And a foo/composer.json file:
+      """
+      {
+          "name": "wp-cli/one-space-test",
+          "description": "Test",
+          "extra": {
+              "commands": ["one-space-test"]
+          }
+      }
+      """
+
+    When I run `wp --require=foo/command.php scaffold package-readme foo`
+    Then the foo/README.md file should exist
+    And the contents of the foo/README.md file should match /\t\tShow extended version information/
+    And the contents of the foo/README.md file should match /\t\tNote: to retrieve/

src/ScaffoldPackageCommand.php

@@ -423,7 +423,7 @@ public function package_readme( $args, $assoc_args ) {
 					$longdesc = (string) preg_replace( '/##\s(.+)/', '**$1**', $longdesc );
 
 					// definition lists
-					$longdesc = preg_replace_callback( '/([^\n]+)\n: (.+?)(\n\n(?=\S)|\n*$)/s', [ __CLASS__, 'rewrap_param_desc' ], $longdesc );
+					$longdesc = preg_replace_callback( '/([^\n]+)\n: (.+?)(\n\n(?=[^\n]+\n: |\*\*)|\n*$)/s', [ __CLASS__, 'rewrap_param_desc' ], $longdesc );
 
 					$command_data = [
 						'name'      => "wp {$command}",
@@ -836,10 +836,38 @@ public function package_tests( $args, $assoc_args ) {
 
 	private static function rewrap_param_desc( $matches ) {
 		$param = $matches[1];
-		$desc  = self::indent( "\t\t", rtrim( $matches[2] ) );
+		$desc  = self::indent( "\t\t", self::normalize_desc_indentation( rtrim( $matches[2] ) ) );
 		return "\t$param\n$desc\n\n";
 	}
 
+	private static function normalize_desc_indentation( $text ) {
+		$paragraphs = explode( "\n\n", $text );
+		foreach ( $paragraphs as &$paragraph ) {
+			$lines      = explode( "\n", $paragraph );
+			$min_indent = PHP_INT_MAX;
+			foreach ( $lines as $line ) {
+				if ( '' !== trim( $line ) ) {
+					$stripped = ltrim( $line );
+					$indent   = strlen( $line ) - strlen( $stripped );
+					if ( $indent < $min_indent ) {
+						$min_indent = $indent;
+					}
+				}
+			}
+			if ( $min_indent > 0 && PHP_INT_MAX !== $min_indent ) {
+				foreach ( $lines as &$line ) {
+					if ( '' !== $line ) {
+						$line = substr( $line, $min_indent );
+					}
+				}
+				unset( $line );
+				$paragraph = implode( "\n", $lines );
+			}
+		}
+		unset( $paragraph );
+		return implode( "\n\n", $paragraphs );
+	}
+
 	private static function indent( $whitespace, $text ) {
 		$lines = explode( "\n", $text );
 		foreach ( $lines as &$line ) {