Add signature for locators in the code generator (#1498)

This also provides better failure mode in case of invalid metadata
instead of failing with a TypeError.

Author: stof

src/Definition/ErrorWaiterAcceptor.php

@@ -11,6 +11,12 @@ class ErrorWaiterAcceptor extends WaiterAcceptor
 {
     public function getError(): ExceptionShape
     {
-        return ($this->shapeLocator)($this->data['expected']);
+        $shape = ($this->shapeLocator)($this->data['expected']);
+
+        if (!$shape instanceof ExceptionShape) {
+            throw new \InvalidArgumentException(sprintf('The error "%s" of the waiter acceptor should have an Exception shape.', $this->data['expected']));
+        }
+
+        return $shape;
     }
 }

src/Definition/Member.php

@@ -15,10 +15,13 @@ class Member
     protected $data;
 
     /**
-     * @var \Closure
+     * @var \Closure(string, Member|null=, array<string, mixed>=): Shape
      */
     protected $shapeLocator;
 
+    /**
+     * @param \Closure(string, Member|null=, array<string, mixed>=): Shape $shapeLocator
+     */
     public function __construct(array $data, \Closure $shapeLocator)
     {
         if (isset($data['endpointdiscoveryid'])) {

src/Definition/Operation.php

@@ -35,14 +35,17 @@ class Operation
     private $example;
 
     /**
-     * @var \Closure
+     * @var \Closure(string, Member|null=, array<string, mixed>=): Shape
      */
     private $shapeLocator;
 
     private function __construct()
     {
     }
 
+    /**
+     * @param \Closure(string, Member|null=, array<string, mixed>=): Shape $shapeLocator
+     */
     public static function create(string $name, array $data, ServiceDefinition $service, ?Pagination $pagination, Example $example, \Closure $shapeLocator): self
     {
         $operation = new self();
@@ -97,7 +100,13 @@ public function getExample(): Example
     public function getOutput(): ?StructureShape
     {
         if (isset($this->data['output']['shape'])) {
-            return ($this->shapeLocator)($this->data['output']['shape'], null, ['resultWrapper' => $this->data['output']['resultWrapper'] ?? null]);
+            $shape = ($this->shapeLocator)($this->data['output']['shape'], null, ['resultWrapper' => $this->data['output']['resultWrapper'] ?? null]);
+
+            if (!$shape instanceof StructureShape) {
+                throw new \InvalidArgumentException(sprintf('The operation "%s" should have an Structure output.', $this->getName()));
+            }
+
+            return $shape;
         }
 
         return null;
@@ -113,8 +122,11 @@ public function getErrors(): array
             if (isset($errors[$error['shape']])) {
                 continue;
             }
-            /** @var ExceptionShape $shape */
             $shape = ($this->shapeLocator)($error['shape']);
+            if (!$shape instanceof ExceptionShape) {
+                throw new \InvalidArgumentException(sprintf('The error "%s" of the operation "%s" should have an Exception shape.', $error['shape'], $this->getName()));
+            }
+
             $errors[$error['shape']] = $shape;
         }
 
@@ -200,11 +212,9 @@ private function getInputShape(): Shape
         return Shape::create(
             sprintf('%sRequest', $this->getName()),
             ['type' => 'structure', 'required' => [], 'members' => []],
+            $this->shapeLocator,
             function () {
-                return null;
-            },
-            function () {
-                return null;
+                return $this->service;
             }
         );
     }

src/Definition/ServiceDefinition.php

@@ -169,7 +169,7 @@ private function getExample(string $name): Example
     /**
      * @param array<string, mixed> $extra
      */
-    private function getShape(string $name, ?Member $member, array $extra): ?Shape
+    private function getShape(string $name, ?Member $member, array $extra): Shape
     {
         if (isset($this->definition['shapes'][$name])) {
             $documentationMember = null;
@@ -181,11 +181,11 @@ private function getShape(string $name, ?Member $member, array $extra): ?Shape
             return Shape::create($name, $this->definition['shapes'][$name] + ['_documentation_main' => $documentationMain, '_documentation_member' => $documentationMember] + $extra, $this->createClosureToFindShape(), $this->createClosureToService());
         }
 
-        return null;
+        throw new \InvalidArgumentException(sprintf('The shape "%s" does not exist.', $name));
     }
 
     /**
-     * @return \Closure(string, ?Member=, array<string, mixed>=): ?Shape
+     * @return \Closure(string, ?Member=, array<string, mixed>=): Shape
      */
     private function createClosureToFindShape(): \Closure
     {
@@ -209,14 +209,20 @@ private function createClosureToService(): \Closure
     }
 
     /**
-     * @return \Closure(string): ?Operation
+     * @return \Closure(string): Operation
      */
     private function createClosureToFindOperation(): \Closure
     {
         $definition = $this;
 
-        return \Closure::fromCallable(function (string $name) use ($definition): ?Operation {
-            return $definition->getOperation($name);
+        return \Closure::fromCallable(function (string $name) use ($definition): Operation {
+            $operation = $definition->getOperation($name);
+
+            if (null === $operation) {
+                throw new \InvalidArgumentException(sprintf('The operation "%s" is not defined.', $name));
+            }
+
+            return $operation;
         });
     }
 }

src/Definition/Shape.php

@@ -15,12 +15,12 @@ class Shape
     protected $data;
 
     /**
-     * @var \Closure
+     * @var \Closure(string, Member|null=, array<string, mixed>=): Shape
      */
     protected $shapeLocator;
 
     /**
-     * @var \Closure
+     * @var \Closure(): ServiceDefinition
      */
     protected $serviceLocator;
 
@@ -33,6 +33,10 @@ private function __construct()
     {
     }
 
+    /**
+     * @param \Closure(string, Member|null=, array<string, mixed>=): Shape $shapeLocator
+     * @param \Closure(): ServiceDefinition $serviceLocator
+     */
     public static function create(string $name, array $data, \Closure $shapeLocator, \Closure $serviceLocator): Shape
     {
         switch ($data['type']) {

src/Definition/Waiter.php

@@ -15,15 +15,19 @@ class Waiter
     private $data;
 
     /**
-     * @var \Closure
+     * @var \Closure(string): Operation
      */
     private $operationLocator;
 
     /**
-     * @var \Closure
+     * @var \Closure(string, Member|null=, array<string, mixed>=): Shape
      */
     private $shapeLocator;
 
+    /**
+     * @param \Closure(string): Operation $operationLocator
+     * @param \Closure(string, Member|null=, array<string, mixed>=): Shape $shapeLocator
+     */
     public function __construct(array $data, \Closure $operationLocator, \Closure $shapeLocator)
     {
         $this->data = $data;

src/Definition/WaiterAcceptor.php

@@ -23,14 +23,17 @@ class WaiterAcceptor
     protected $data;
 
     /**
-     * @var \Closure
+     * @var \Closure(string, Member|null=, array<string, mixed>=): Shape
      */
     protected $shapeLocator;
 
     private function __construct()
     {
     }
 
+    /**
+     * @param \Closure(string, Member|null=, array<string, mixed>=): Shape $shapeLocator
+     */
     public static function create(array $data, \Closure $shapeLocator): self
     {
         switch ($data['matcher']) {