bugfix: omit PHPStan method annotations from Ec2Client (#3349)

Author: stobrien89

build/ClientAnnotator.php

@@ -15,10 +15,10 @@
  *      read this tag; PhpStorm ignores it entirely (so its parser doesn't
  *      trip on array shapes it doesn't understand).
  *
- * Pairing invariant: every legacy `@method` must have a matching
- * `@phpstan-method`. When an operation has no modeled input (or its input
- * shape is empty), we still emit the unsealed empty shape `array{...}` so
- * consumers and static-analysis tools see a uniform surface across all
+ * Unless a service is explicitly excluded, every legacy `@method` has a
+ * matching `@phpstan-method`. When an operation has no modeled input (or its
+ * input shape is empty), we still emit the unsealed empty shape `array{...}`
+ * so consumers and static-analysis tools see a uniform surface across all
  * operations.
  */
 class ClientAnnotator
@@ -36,6 +36,15 @@ class ClientAnnotator
     private const GENERATED_ANNOTATION_PATTERN =
         '/^\* @(?:phpstan-)?method (\\\\Aws\\\\Result|\\\\GuzzleHttp\\\\Promise\\\\Promise)[ <(]/';
 
+    /**
+     * EC2's inline shapes make Ec2Client.php large enough that PHPStan may
+     * not terminate when resolving the class. Keep its legacy annotations
+     * while a more compact representation is investigated.
+     */
+    private const PHPSTAN_METHOD_EXCLUDED_ENDPOINTS = [
+        'ec2',
+    ];
+
     /** @var ReflectionClass */
     private $reflection;
 
@@ -114,16 +123,17 @@ public function updateApiMethodAnnotations()
     }
 
     /**
-     * Returns the list of docblock lines to emit. Each operation produces
-     * a `@method` line (for PhpStorm + runtime baseline) immediately
-     * followed by a `@phpstan-method` line (or lines, for multi-line
-     * shapes) carrying the input array shape (for PHPStan/Psalm). When
-     * the operation has no modeled input, we fall back to `array{...}`
-     * so the pair invariant always holds.
+     * Returns the list of docblock lines to emit. Each operation produces a
+     * `@method` line for PhpStorm and other IDEs. Unless the service is
+     * excluded, it is immediately followed by a `@phpstan-method` line (or
+     * lines, for multi-line shapes) carrying the input array shape for
+     * PHPStan and Psalm. When the operation has no modeled input, we fall
+     * back to `array{...}`.
      */
     private function getMethodAnnotations()
     {
         $annotations = [];
+        $emitPhpstanMethods = $this->shouldEmitPhpstanMethodAnnotations();
         $latestVersion = $this->getLatestVersion();
 
         foreach ($this->getMethods() as $command => $apiVersions) {
@@ -132,29 +142,28 @@ private function getMethodAnnotations()
                 "{$command}Async" => '\\GuzzleHttp\\Promise\\Promise',
             ];
 
-            // Look up the input shape once per operation. Both the sync
-            // and async variants share the same input.
-            //
-            // When the operation has no modeled input (`input` key absent
-            // from api-2.json, e.g. AutoScaling::DescribeAdjustmentTypes,
-            // Acm::GetAccountConfiguration) or its input shape is empty,
-            // we still emit a paired `@phpstan-method` carrying the
-            // unsealed empty shape `array{...}`. Keeping the pair
-            // invariant means downstream consumers and the sweep tool
-            // never see a mixed `@method`/`@phpstan-method` surface.
-            $inputShape = $this->resolveInputShape(
-                $command,
-                $latestVersion,
-                $apiVersions
-            );
-            $renderedShape = ($inputShape !== null)
-                ? $this->getFormatter($latestVersion)->formatInput($inputShape)
-                : 'array{...}';
-            if ($renderedShape === null) {
-                // Formatter returned null for an exotic shape (e.g. an
-                // input keyed to a non-structure type). Fall back to the
-                // unsealed empty shape so the pair invariant still holds.
-                $renderedShape = 'array{...}';
+            if ($emitPhpstanMethods) {
+                // Look up the input shape once per operation. Both the sync
+                // and async variants share the same input.
+                //
+                // When the operation has no modeled input (`input` key absent
+                // from api-2.json, e.g. AutoScaling::DescribeAdjustmentTypes,
+                // Acm::GetAccountConfiguration) or its input shape is empty,
+                // emit the unsealed empty shape `array{...}`.
+                $inputShape = $this->resolveInputShape(
+                    $command,
+                    $latestVersion,
+                    $apiVersions
+                );
+                $renderedShape = ($inputShape !== null)
+                    ? $this->getFormatter($latestVersion)
+                        ->formatInput($inputShape)
+                    : 'array{...}';
+                if ($renderedShape === null) {
+                    // Formatter returned null for an exotic shape (e.g. an
+                    // input keyed to a non-structure type).
+                    $renderedShape = 'array{...}';
+                }
             }
 
             foreach ($commandMethods as $method => $returnType) {
@@ -164,12 +173,14 @@ private function getMethodAnnotations()
                     $apiVersions
                 );
 
-                foreach ($this->getPhpstanAnnotationLines(
-                    $method,
-                    $returnType,
-                    $renderedShape
-                ) as $line) {
-                    $annotations []= $line;
+                if ($emitPhpstanMethods) {
+                    foreach ($this->getPhpstanAnnotationLines(
+                        $method,
+                        $returnType,
+                        $renderedShape
+                    ) as $line) {
+                        $annotations []= $line;
+                    }
                 }
             }
         }
@@ -333,6 +344,15 @@ private function getLatestVersion(): string
         return end($versions);
     }
 
+    private function shouldEmitPhpstanMethodAnnotations(): bool
+    {
+        return !in_array(
+            $this->getEndpoint(),
+            self::PHPSTAN_METHOD_EXCLUDED_ENDPOINTS,
+            true
+        );
+    }
+
     private function getApiDefinition($version = 'latest')
     {
         $provider = ApiProvider::defaultProvider();

build/PhpstanShapeFormatter.php

@@ -94,14 +94,12 @@ public function __construct(array $apiDefinition)
      * or not a structure type).
      *
      * Empty-input operations (modeled as a structure with `"members": {}`)
-     * return the unsealed empty shape `array{...}`. This keeps the
-     * `@method` / `@phpstan-method` pairing invariant in ClientAnnotator —
-     * every legacy `@method` we emit must have a matching `@phpstan-method`
-     * so consumers and static-analysis tools never see a mixed surface.
-     * `array{...}` is an unsealed array shape with no required keys, so it
-     * accepts any `array` at runtime without flagging extra keys — exactly
-     * the semantics consumers want for an op that takes no modeled args
-     * but may receive an empty (or sentinel) array.
+     * return the unsealed empty shape `array{...}`. For services that emit
+     * PHPStan annotations, this keeps the `@method` / `@phpstan-method`
+     * pairing invariant. `array{...}` is an unsealed array shape with no
+     * required keys, so it accepts any `array` at runtime without flagging
+     * extra keys — exactly the semantics consumers want for an op that takes
+     * no modeled args but may receive an empty (or sentinel) array.
      *
      * @param string $inputShapeName Name of the input shape from operations[op].input.shape
      * @return string|null PHPStan/Psalm array-shape string, multi-line for nested shapes