MCLOUD-6530: Fix an issue with empty error code in the StepException (magento#763)

Author: oshmyheliuk

config/schema.error.yaml

@@ -331,6 +331,12 @@
     suggestion: 'Support for the Braintree module is no longer included with Magento 2.4.0 and later. Remove the CONFIG__STORES__DEFAULT__PAYMENT__BRAINTREE__CHANNEL variable from the variables section of the .magento.app.yaml file. For Braintree support, use an official Braintree Payments extension from the Magento Marketplace instead.'
     stage: deploy
     type: critical
+!php/const Magento\MagentoCloud\App\Error::DEPLOY_WRONG_SEARCH_ENGINE:
+    step: validate-config
+    title: 'Magento 2.4.0 requires Elasticsearch service to be installed'
+    suggestion: 'Install Elasticsearch service'
+    stage: deploy
+    type: critical
 !php/const Magento\MagentoCloud\App\Error::PD_DEPLOY_IS_FAILED:
     step: is-deploy-failed
     title: 'Deploy stage failed'

dist/error-codes.md

@@ -1,12 +1,13 @@
-
+<!-Note: The error code tables in this file are auto-generated from source code. To request changes to error code descriptions or suggestions, submit a GitHub issue to the magento/ece-tools repository.->
 
 ## Critical Errors
 
+Critical errors indicate a problem with the Magento Commerce Cloud project configuration that causes deployment failure, for example incorrect, unsupported, or missing configuration for required settings. Before you can deploy, you must update the configuration to resolve these errors.
 
 ### Build stage
 
 {:.error-table}
-| Error code | Build step | Error description | Suggested action |
+| Error code | Build step | Error description (Title) | Suggested action |
 | - | - | - | - |
 | 2 |  | Cannot write to the `./app/etc/env.php` file | Deployment script cannot make required changes to the `/app/etc/env.php` file. Check your filesystem permissions. |
 | 3 |  | Configuration isn't defined in the `schema.yaml` file | Configuration is not defined in the `./vendor/magento/ece-tools/config/schema.yaml` file. Check that the config variable name is correct, and that it is defined. |
@@ -37,7 +38,7 @@
 ### Deploy stage
 
 {:.error-table}
-| Error code | Deploy step | Error description | Suggested action |
+| Error code | Deploy step | Error description (Title) | Suggested action |
 | - | - | - | - |
 | 101 | pre-deploy: cache | Incorrect cache configuration (missing port or host) | Cache configuration is missing required parameters `server` or `port`. Check the `cloud.log` for more information. |
 | 102 |  | Cannot write to the `./app/etc/env.php` file | Deployment script cannot make required changes to the `/app/etc/env.php` file. Check your filesystem permissions. |
@@ -72,11 +73,12 @@
 | 131 | install-update | The `crypt/key`  key value does not exist in the `./app/etc/env.php` file or the `CRYPT_KEY` cloud environment variable | This error occurs if the `./app/etc/env.php` file is not present when Magento deployment begins, or if the `crypt/key` value is undefined. If you migrated the database from another environment, retrieve the crypt key value from that environment. Then, add the value to the [CRYPT_KEY](https://devdocs.magento.com/cloud/env/variables-deploy.html#crypt_key) cloud environment variable in your current environment. See [Add the Magento encryption key](https://devdocs.magento.com/cloud/setup/first-time-setup-import-import.html#encryption-key). If you accidentally removed the `./app/etc/env.php` file, use the following command to restore it from the backup files created from a previous deployment: `./vendor/bin/ece-tools backup:restore` CLI command ." |
 | 132 |  | Can not connect to the Elasticsearch service | Check that credentials for elasticsearch are correct and service is running |
 | 133 | validate-config | Remove Magento Braintree module configuration which is no longer supported in Magento 2.4 and later versions. | Support for the Braintree module is no longer included with Magento 2.4.0 and later. Remove the CONFIG__STORES__DEFAULT__PAYMENT__BRAINTREE__CHANNEL variable from the variables section of the .magento.app.yaml file. For Braintree support, use an official Braintree Payments extension from the Magento Marketplace instead. |
+| 134 | validate-config | Magento 2.4.0 requires Elasticsearch service to be installed | Install Elasticsearch service |
 
 ### Post-deploy stage
 
 {:.error-table}
-| Error code | Post-deploy step | Error description | Suggested action |
+| Error code | Post-deploy step | Error description (Title) | Suggested action |
 | - | - | - | - |
 | 201 | is-deploy-failed | Deploy stage failed |  |
 | 202 |  | The `./app/etc/env.php` file is not writable | Deployment script cannot make required changes to the `/app/etc/env.php` file. Check your filesystem permissions. |
@@ -91,21 +93,21 @@
 ### General
 
 {:.error-table}
-| Error code | General step | Error description | Suggested action |
+| Error code | General step | Error description (Title) | Suggested action |
 | - | - | - | - |
 | 243 |  | Configuration is not defined in the `schema.yaml` file | Check that the config variable name is correct, and that it defined. |
 | 244 |  | Failed to parse the `.magento.env.yaml` file | The `./.magento.env.yaml` file format is invalid. Use a YAML parser to check the syntax and fix any errors. |
 | 245 |  | Unable to read the `.magento.env.yaml` file | Unable to read the `./.magento.env.yaml` file. Check file permissions. |
 | 246 |  | Unable to read the `.schema.yaml` file |  |
 
-
 ## Warning Errors
 
+Warning errors indicate a problem with the Magento Commerce Cloud project configuration such as incorrect, deprecated, unsupported, or missing configuration settings for optional features that can affect site operation. Although a warning does not cause deployment failure, you should review warning messages and update the configuration to resolve them.
 
 ### Build stage
 
 {:.error-table}
-| Error code | Build step | Error description | Suggested action |
+| Error code | Build step | Error description (Title) | Suggested action |
 | - | - | - | - |
 | 1001 | validate-config | File app/etc/config.php does not exist |  |
 | 1002 | validate-config | The ./build_options.ini file is no longer supported |  |
@@ -118,7 +120,7 @@
 ### Deploy stage
 
 {:.error-table}
-| Error code | Deploy step | Error description | Suggested action |
+| Error code | Deploy step | Error description (Title) | Suggested action |
 | - | - | - | - |
 | 2001 | pre-deploy:cache | Cache is configured for a Redis service that is not available. Configuration will be ignored. |  |
 | 2002 | validate-config | The configured state is not ideal |  |
@@ -149,7 +151,7 @@
 ### Post-deploy stage
 
 {:.error-table}
-| Error code | Post-deploy step | Error description | Suggested action |
+| Error code | Post-deploy step | Error description (Title) | Suggested action |
 | - | - | - | - |
 | 3001 | validate-config | Debug logging is enabled in Magento | To save disk space, do not enable debug logging for your production environments. |
 | 3002 | warm-up | Can not fetch store urls |  |
@@ -158,7 +160,7 @@
 ### General
 
 {:.error-table}
-| Error code | General step | Error description | Suggested action |
+| Error code | General step | Error description (Title) | Suggested action |
 | - | - | - | - |
 | 4001 |  | Can not get system processor count: |  |
 

src/App/Error.php

@@ -12,6 +12,8 @@
  */
 class Error
 {
+    public const DEFAULT_ERROR = 1;
+
     public const BUILD_ENV_PHP_IS_NOT_WRITABLE = 2;
     public const BUILD_CONFIG_NOT_DEFINED = 3;
     public const BUILD_CONFIG_PARSE_FAILED = 4;
@@ -71,6 +73,7 @@ class Error
     public const DEPLOY_CRYPT_KEY_IS_ABSENT = 131;
     public const DEPLOY_ES_CANNOT_CONNECT = 132;
     public const DEPLOY_WRONG_BRAINTREE_VARIABLE = 133;
+    public const DEPLOY_WRONG_SEARCH_ENGINE = 134;
 
     public const PD_DEPLOY_IS_FAILED = 201;
     public const PD_ENV_PHP_IS_NOT_WRITABLE = 202;

src/Command/Dev/GenerateSchemaError.php

@@ -124,17 +124,21 @@ private function groupErrors(array $errors): array
      */
     private function generateDocs(array $errors): string
     {
-        $result = '';
+        $result = '<!-Note: The error code tables in this file are auto-generated from source code. ' .
+            'To request changes to error code descriptions or suggestions, ' .
+            'submit a GitHub issue to the magento/ece-tools repository.->';
+        $result .= "\n";
 
         foreach ($errors as $type => $typeErrors) {
-            $result .= sprintf("\n\n## %s Errors\n\n", ucfirst($type));
+            $result .= sprintf("\n## %s Errors\n", ucfirst($type));
+            $result .= sprintf("\n%s\n", $this->getErrorTypeDescription()[$type]);
 
             foreach ($typeErrors as $stage => $stageErrors) {
-                $result .= sprintf("\n### %s%s\n\n", ucfirst($stage), $stage === 'general' ? '' : ' stage');
+                $result .= sprintf("\n### %s%s\n", ucfirst($stage), $stage === 'general' ? '' : ' stage');
 
-                $table = "{:.error-table}\n";
+                $table = "\n{:.error-table}\n";
                 $table .= sprintf(
-                    "| Error code | %s step | Error description | Suggested action |\n",
+                    "| Error code | %s step | Error description (Title) | Suggested action |\n",
                     ucfirst($stage)
                 );
                 $table .= "| - | - | - | - |\n";
@@ -154,4 +158,22 @@ private function generateDocs(array $errors): string
 
         return $result . self::FOOTER_SCRIPTS;
     }
+
+    /**
+     * Returns an array of error types description (warning and critical)
+     *
+     * @return array
+     */
+    public function getErrorTypeDescription(): array
+    {
+        return [
+            'critical' => 'Critical errors indicate a problem with the Magento Commerce Cloud project configuration ' .
+                'that causes deployment failure, for example incorrect, unsupported, or missing configuration for ' .
+                'required settings. Before you can deploy, you must update the configuration to resolve these errors.',
+            'warning' => 'Warning errors indicate a problem with the Magento Commerce Cloud project configuration ' .
+                'such as incorrect, deprecated, unsupported, or missing configuration settings for optional features ' .
+                'that can affect site operation. Although a warning does not cause deployment failure, you ' .
+                'should review warning messages and update the configuration to resolve them.',
+        ];
+    }
 }

src/Config/Validator/Deploy/ElasticSearchIntegrity.php

@@ -7,9 +7,11 @@
 
 namespace Magento\MagentoCloud\Config\Validator\Deploy;
 
+use Magento\MagentoCloud\App\Error;
 use Magento\MagentoCloud\Config\Validator;
 use Magento\MagentoCloud\Config\ValidatorException;
 use Magento\MagentoCloud\Config\ValidatorInterface;
+use Magento\MagentoCloud\Filesystem\FileSystemException;
 use Magento\MagentoCloud\Package\MagentoVersion;
 use Magento\MagentoCloud\Package\UndefinedPackageException;
 use Magento\MagentoCloud\Service\ElasticSearch;
@@ -58,9 +60,9 @@ public function validate(): Validator\ResultInterface
             if ($this->magentoVersion->isGreaterOrEqual('2.4.0')
                 && !$this->elasticsearch->isInstalled()
             ) {
-                return $this->resultFactory->error('Magento 2.4.0 requires Elasticsearch service to be installed.');
+                return $this->resultFactory->errorByCode(Error::DEPLOY_WRONG_SEARCH_ENGINE);
             }
-        } catch (UndefinedPackageException $exception) {
+        } catch (UndefinedPackageException | FileSystemException $exception) {
             throw new ValidatorException($exception->getMessage(), $exception->getCode(), $exception);
         }
 

src/Step/ValidateConfiguration.php

@@ -7,6 +7,7 @@
 
 namespace Magento\MagentoCloud\Step;
 
+use Magento\MagentoCloud\App\Error as AppError;
 use Magento\MagentoCloud\App\Logger;
 use Magento\MagentoCloud\Config\Validator\Result\Error;
 use Magento\MagentoCloud\Config\ValidatorException;
@@ -65,7 +66,7 @@ public function execute(): void
 
                 if ($level >= ValidatorInterface::LEVEL_CRITICAL) {
                     $error = array_values($levelErrors)[0];
-                    throw new StepException($error->getError(), $error->getErrorCode());
+                    throw new StepException($error->getError(), $error->getErrorCode() ?: AppError::DEFAULT_ERROR);
                 }
             }
         }

src/Test/Unit/Config/Validator/Deploy/ElasticsearchIntegrityTest.php

@@ -7,6 +7,7 @@
 
 namespace Magento\MagentoCloud\Test\Unit\Config\Validator\Deploy;
 
+use Magento\MagentoCloud\App\Error;
 use Magento\MagentoCloud\Config\Validator\Deploy\ElasticSearchIntegrity;
 use Magento\MagentoCloud\Config\Validator\ResultFactory;
 use Magento\MagentoCloud\Config\ValidatorException;
@@ -84,7 +85,8 @@ public function testValidateNoElasticSearch(): void
             ->method('isInstalled')
             ->willReturn(false);
         $this->resultFactoryMock->expects($this->once())
-            ->method('error');
+            ->method('errorByCode')
+            ->with(Error::DEPLOY_WRONG_SEARCH_ENGINE);
 
         $this->validator->validate();
     }

src/Test/Unit/Step/ValidateConfigurationTest.php

@@ -7,6 +7,7 @@
 
 namespace Magento\MagentoCloud\Test\Unit\Step;
 
+use Magento\MagentoCloud\App\Error;
 use Magento\MagentoCloud\App\Logger;
 use Magento\MagentoCloud\Config\Validator\Result;
 use Magento\MagentoCloud\Config\ValidatorInterface;
@@ -90,6 +91,31 @@ public function testExecuteWithCriticalError(): void
         $step->execute();
     }
 
+    /**
+     * @throws StepException
+     */
+    public function testExecuteWithCriticalErrorAndEmptyErrorCode(): void
+    {
+        $this->expectException(StepException::class);
+        $this->expectExceptionMessage('some error');
+        $this->expectExceptionCode(Error::DEFAULT_ERROR);
+
+        $this->loggerMock->expects($this->once())
+            ->method('log')
+            ->with(ValidatorInterface::LEVEL_CRITICAL, 'some error');
+
+        $step = new ValidateConfiguration(
+            $this->loggerMock,
+            [
+                ValidatorInterface::LEVEL_CRITICAL => [
+                    $this->createValidatorWithError('some error', 'some  suggestion'),
+                ],
+            ]
+        );
+
+        $step->execute();
+    }
+
     /**
      * @throws StepException
      */