Exclude command namespaces and missing commands from README generation

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

Author: Copilot

features/scaffold-package-readme.feature

@@ -386,3 +386,46 @@ Feature: Scaffold a README.md file for an existing package
       """
       **Alias:** `cpt`
       """
+
+  Scenario: README excludes command namespaces
+    Given an empty directory
+    And a foo/composer.json file:
+      """
+      {
+          "name": "wp-cli/namespace-test",
+          "description": "Test package for excluding command namespaces",
+          "license": "MIT",
+          "authors": [],
+          "minimum-stability": "dev",
+          "autoload": {
+              "files": [ "command.php" ]
+          },
+          "require": {
+              "wp-cli/wp-cli": "^2.12"
+          },
+          "require-dev": {
+              "wp-cli/wp-cli-tests": "^5.0.0"
+          },
+          "extra": {
+              "commands": [
+                "i18n",
+                "i18n make-pot"
+              ]
+          }
+      }
+      """
+
+    When I run `wp scaffold package-readme foo`
+    Then the foo/README.md file should exist
+    And the foo/README.md file should not contain:
+      """
+      ### wp i18n
+      """
+    And the foo/README.md file should not contain:
+      """
+      ### wp i18n make-pot
+      """
+    And the foo/README.md file should contain:
+      """
+      ## Using
+      """

src/ScaffoldPackageCommand.php

@@ -339,16 +339,33 @@ public function package_readme( $args, $assoc_args ) {
 				}
 				 */
 
+				// Skip commands that were not found or are namespaces with no meaningful content.
+				if ( false === $parent_command ) {
+					continue;
+				}
+
+				// Skip command namespaces (commands with subcommands but no meaningful content).
+				// This needs to be done before processing longdesc to accurately detect empty content.
+				$has_subcommands = ! empty( $parent_command['subcommands'] );
+				$shortdesc       = isset( $parent_command['description'] ) ? $parent_command['description'] : '';
+				$raw_longdesc    = isset( $parent_command['longdesc'] ) ? $parent_command['longdesc'] : '';
+				$is_namespace    = $has_subcommands && empty( trim( $shortdesc ) ) && empty( trim( $raw_longdesc ) );
+
+				if ( $is_namespace ) {
+					continue;
+				}
+
 				$longdesc = isset( $parent_command['longdesc'] ) ? $parent_command['longdesc'] : '';
 				$longdesc = (string) preg_replace( '/## GLOBAL PARAMETERS(.+)/s', '', $longdesc );
 				$longdesc = (string) preg_replace( '/##\s(.+)/', '**$1**', $longdesc );
 
 				// definition lists
 				$longdesc = preg_replace_callback( '/([^\n]+)\n: (.+?)(\n\n|$)/s', [ __CLASS__, 'rewrap_param_desc' ], $longdesc );
 
+				$shortdesc    = isset( $parent_command['description'] ) ? $parent_command['description'] : '';
 				$command_data = [
 					'name'      => "wp {$command}",
-					'shortdesc' => isset( $parent_command['description'] ) ? $parent_command['description'] : '',
+					'shortdesc' => $shortdesc,
 					'synopsis'  => "wp {$command}" . ( empty( $parent_command['subcommands'] ) ? ( isset( $parent_command['synopsis'] ) ? " {$parent_command['synopsis']}" : '' ) : '' ),
 					'longdesc'  => $longdesc,
 				];