[#3110] Reconciled comments and docblocks with the code they describe.

.vortex/installer/src/Command/InstallCommand.php

@@ -32,8 +32,6 @@
 use Symfony\Component\Console\Output\OutputInterface;
 
 /**
- * Run command.
- *
  * Install command.
  */
 class InstallCommand extends Command implements CommandRunnerAwareInterface, ExecutableFinderAwareInterface {

.vortex/installer/src/Prompts/Handlers/CustomModules.php

@@ -211,8 +211,8 @@ protected function discoverModulePrefix(): ?string {
   /**
    * Remove Behat feature files tagged with @demo.
    *
-   * Scans the Behat features directory for .feature files whose first line
-   * contains the @demo tag and removes them.
+   * Removes every file in the Behat features directory that contains
+   * the @demo tag anywhere in its contents.
    *
    * @param string $dir
    *   The base directory to search in.

.vortex/installer/src/Prompts/Handlers/HandlerInterface.php

@@ -118,7 +118,7 @@ public function options(array $responses): ?array;
    *   Array of collected responses.
    *
    * @return bool
-   *   The condition callback, or null if not conditional.
+   *   TRUE if the handler should run, FALSE otherwise.
    */
   public function shouldRun(array $responses): bool;
 
@@ -134,10 +134,10 @@ public function shouldRun(array $responses): bool;
   public function default(array $responses): null|string|bool|array;
 
   /**
-   * Discover the value from the environment.
+   * Discover the value from the existing codebase.
    *
    * @return null|string|bool|array
-   *   The value of the environment variable.
+   *   The discovered value, or NULL if it could not be discovered.
    */
   public function discover(): null|string|bool|array;
 
@@ -176,8 +176,7 @@ public function resolvedValue(array $responses): null|string|bool|array;
   /**
    * Get a message to display when showing the resolved value.
    *
-   * This is used by handlerManager to show an appropriate message (via
-   * info(), ok(), etc.) when using a resolved value instead of handlering
+   * The message is shown when a resolved value is used instead of prompting
    * for input.
    *
    * @param array $responses

.vortex/installer/src/Prompts/PromptManager.php

@@ -119,8 +119,8 @@ public function __construct(
   /**
    * Run prompts to get responses.
    *
-   * If non-interactive mode is used, the values provided by $this->default()
-   * method, including discovery from the existing codebase, will be used.
+   * In non-interactive mode, each prompt returns its default, which includes
+   * values discovered from the existing codebase.
    */
   public function runPrompts(): void {
     // Quiet the TUI output in non-interactive mode; the original verbosity is
@@ -628,9 +628,8 @@ protected function initHandlers(): void {
   /**
    * Resolve prompt overrides from --prompts CLI option.
    *
-   * Reads the raw prompt array from Config, normalizes keys to handler IDs,
-   * validates values against handler types and options, and stores the
-   * validated overrides.
+   * Reads the raw prompt array from Config, validates values against handler
+   * types and options, and stores the validated overrides.
    *
    * @throws \RuntimeException
    *   If any prompt value is invalid.
@@ -650,7 +649,6 @@ protected function resolvePromptOverrides(): void {
       throw new \RuntimeException(sprintf('Invalid --prompts values: %s.', implode('; ', $messages)));
     }
 
-    // Use the resolved values which include defaults for missing prompts.
     foreach ($raw as $key => $value) {
       if (isset($this->handlers[$key])) {
         $this->promptOverrides[$key] = $value;
@@ -682,7 +680,6 @@ protected function prompt(string $handler_class, array $responses = []): mixed {
    *
    * @param string $handler_class
    *   The handler class name.
-   *   The handler id.
    * @param mixed $default_override
    *   Optional override for the default value (for response dependencies).
    * @param array $responses

.vortex/installer/src/Schema/SchemaValidator.php

@@ -37,10 +37,8 @@ public function validate(array $config): array {
     $warnings = [];
     $resolved = [];
 
-    $normalized = $this->normalizeConfig($config);
-
     $known_ids = array_keys($this->handlers);
-    foreach (array_keys($normalized) as $key) {
+    foreach (array_keys($config) as $key) {
       if (!in_array($key, $known_ids, TRUE)) {
         $errors[] = ['prompt' => $key, 'message' => sprintf('Unknown prompt "%s".', $key)];
       }
@@ -51,16 +49,16 @@ public function validate(array $config): array {
         continue;
       }
 
-      $has_value = array_key_exists($id, $normalized);
-      $value = $normalized[$id] ?? NULL;
+      $has_value = array_key_exists($id, $config);
+      $value = $config[$id] ?? NULL;
 
       if (!$has_value) {
         continue;
       }
 
       $depends_on = $handler->dependsOn();
       if ($depends_on !== NULL) {
-        $dep_result = $this->checkDependency($depends_on, $normalized);
+        $dep_result = $this->checkDependency($depends_on, $config);
 
         if ($dep_result === 'skip') {
           $type_error = $this->validateType($handler, $value);
@@ -109,34 +107,13 @@ public function validate(array $config): array {
     ];
   }
 
-  /**
-   * Normalize config keys to handler IDs.
-   *
-   * Supports both env var names (VORTEX_INSTALLER_PROMPT_*) and handler IDs.
-   *
-   * @param array<string, mixed> $config
-   *   The raw config array.
-   *
-   * @return array<string, mixed>
-   *   Config keyed by handler IDs.
-   */
-  protected function normalizeConfig(array $config): array {
-    $normalized = [];
-
-    foreach ($config as $key => $value) {
-      $normalized[$key] = $value;
-    }
-
-    return $normalized;
-  }
-
   /**
    * Check if dependency conditions are met.
    *
    * @param array<string, array<mixed>> $depends_on
    *   The dependency conditions.
    * @param array<string, mixed> $config
-   *   The normalized config.
+   *   The config array, keyed by handler ID.
    *
    * @return bool|string
    *   TRUE if met, FALSE if not met, 'skip' for system dependencies.

.vortex/installer/src/Utils/FileManager.php

@@ -392,8 +392,7 @@ protected function relativePaths(string $directory): array {
    * Remove obsolete paths from previous Vortex versions.
    *
    * Removes paths that previous Vortex versions placed in the destination but
-   * the current version no longer ships. Runs after copyFiles() so legacy
-   * artifacts do not linger across upgrades.
+   * the current version no longer ships.
    */
   public function removeObsoletePaths(): void {
     $destination = $this->config->getDestination();

.vortex/installer/src/Utils/Git.php

@@ -53,7 +53,7 @@ public function listRemotes(): array {
         continue;
         // @codeCoverageIgnoreEnd
       }
-      // Remove the trailing (fetch) or (push) from the remote name.
+      // Remove the trailing (fetch) or (push) from the remote URL.
       $parts[1] = preg_replace('/ \(.*\)$/', '', $parts[1]);
       $remotes[$parts[0]] = $parts[1];
     }

.vortex/installer/src/Utils/Normalizer.php

@@ -4,11 +4,6 @@
 
 namespace DrevOps\VortexInstaller\Utils;
 
-/**
- * Installer configuration.
- *
- * Installer config is a config of this installer script.
- */
 final class Normalizer {
 
   /**

.vortex/installer/src/Utils/OptionsResolver.php

@@ -40,10 +40,9 @@ public static function checkRequirements(ExecutableFinder $finder): void {
    *
    * Installer configuration is a set of internal installer variables
    * prefixed with "VORTEX_INSTALLER_" and used to control the installation.
-   * They are read from the environment variables with $this->config->get().
-   *
-   * For simplicity of naming, internal installer config variables used in
-   * $this->config->get() match environment variables names.
+   * Each is resolved from the CLI options, the --config JSON and the
+   * environment, and stored in Config under the name of its environment
+   * variable.
    *
    * @param array<mixed> $options
    *   Array of CLI options.

.vortex/installer/src/Utils/Validator.php

@@ -4,11 +4,6 @@
 
 namespace DrevOps\VortexInstaller\Utils;
 
-/**
- * Converter.
- *
- * Convert strings to different formats.
- */
 class Validator {
 
   public static function isContainerImage(string $value): bool {
@@ -51,10 +46,11 @@ public static function isGitCommitShaShort(string $value): bool {
    * - Branch names: "main", "develop", "feature/my-feature"
    *
    * Follows git reference naming rules:
-   * - Can contain alphanumeric, dot, hyphen, underscore, slash
+   * - Can contain alphanumeric, dot, hyphen, underscore, slash, plus
    * - Cannot start with dot or hyphen
    * - Cannot contain: @, ^, ~, :, ?, *, [, space, \, @{
-   * - Cannot end with .lock or contain
+   * - Cannot contain .. or //
+   * - Cannot end with .lock or /
    *
    * @param string $value
    *   The reference string to validate.
@@ -73,11 +69,6 @@ public static function isGitRef(string $value): bool {
       return TRUE;
     }
 
-    // Git ref naming rules (simplified):
-    // - Can contain alphanumeric, dot, hyphen, underscore, slash, plus.
-    // - Cannot start with dot or hyphen.
-    // - Cannot contain .. or end with .lock.
-    // - Cannot end with / or contain //.
     $pattern = '/^(?![.\-])(?!.*\.\.)[a-zA-Z0-9._\/+-]+(?<!\.lock)$/';
 
     if (!preg_match($pattern, $value)) {

.vortex/installer/tests/Functional/Command/BuildCommandTest.php

@@ -146,7 +146,7 @@ public function testBuildCommand(
   }
 
   /**
-   * Data provider for testBuildWithMockedRunner.
+   * Data provider for testBuildCommand.
    *
    * @return \Iterator<string, array{exit_code_callback: \Closure, command_inputs: array<string, mixed>, expect_failure: bool, output_assertions: array<string>, requirements_exit_callback?: (\Closure | null), requirements_finder_callback?: (\Closure | null), docker_compose_url?: (string | null), url_service?: string, before?: (\Closure | null)}>
    */

.vortex/installer/tests/Unit/Utils/EnvTest.php

@@ -11,11 +11,6 @@
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\Attributes\RunTestsInSeparateProcesses;
 
-/**
- * Class InstallerDotEnvTest.
- *
- * InstallerDotEnvTest fixture class.
- */
 #[CoversClass(Env::class)]
 #[RunTestsInSeparateProcesses]
 class EnvTest extends UnitTestCase {

.vortex/installer/tests/Unit/Utils/ValidatorTest.php

@@ -9,9 +9,6 @@
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\DataProvider;
 
-/**
- * Class InstallerHelpersTest.
- */
 #[CoversClass(Validator::class)]
 class ValidatorTest extends UnitTestCase {
 

.vortex/tests/lint.ci.sh

@@ -23,3 +23,5 @@ else
   echo "Checking that .circleci/vortex-test-common.yml is up to date."
   php "${ROOT_DIR}/.vortex/tests/generate-vortex-dev-circleci" --check
 fi
+
+# LCOV_EXCL_STOP

.vortex/tests/lint.dockerfiles.sh

@@ -36,3 +36,5 @@ for file in "${targets[@]}"; do
     docker run --rm -i hadolint/hadolint:v2.15.1 <"${file}"
   fi
 done
+
+# LCOV_EXCL_STOP

.vortex/tests/lint.markdown.sh

@@ -33,3 +33,5 @@ done
   "${ROOT_DIR}"/README.md \
   "${ROOT_DIR}"/README.dist.md \
   "${ROOT_DIR}"/SECURITY.md
+
+# LCOV_EXCL_STOP

.vortex/tests/lint.scripts.sh

@@ -79,3 +79,5 @@ for file in "${targets[@]}"; do
     fi
   fi
 done
+
+# LCOV_EXCL_STOP

.vortex/tests/test.common.sh

@@ -39,3 +39,5 @@ bats() {
 }
 
 bats "${BATS_DIR}/unit"
+
+# LCOV_EXCL_STOP

.vortex/tooling/src/vortex-doctor

@@ -2,8 +2,8 @@
 #
 # Check project requirements or print info.
 #
-# doctor.sh - check project requirements.
-# doctor.sh info - show system information.
+# vortex-doctor - check project requirements.
+# vortex-doctor info - show system information.
 #
 # IMPORTANT! This script runs outside the container on the host system.
 #

.vortex/tooling/src/vortex-notify-email

@@ -2,15 +2,16 @@
 ##
 # Notification dispatch to email recipients.
 #
-# Notification dispatch to email recipients.
+# Sends deployment notifications by email using the 'sendmail' or 'mail'
+# command.
 #
 # Usage:
 # VORTEX_NOTIFY_PROJECT="Site Name" \
 # DRUPAL_SITE_EMAIL="from@example.com" \
 # VORTEX_NOTIFY_EMAIL_RECIPIENTS="to1@example.com|Jane Doe, to2@example.com|John Doe" \
 # VORTEX_NOTIFY_LABEL="main" \
 # VORTEX_NOTIFY_ENVIRONMENT_URL="https://environment-url-example.com" \
-# ./notify-email
+# vortex-notify-email
 #
 # shellcheck disable=SC1090,SC1091,SC2016
 

.vortex/tooling/tests/_helper.bash

@@ -26,6 +26,7 @@ setup() {
   # NOTE: If Docker tests fail, re-run with custom temporary directory
   # (must be pre-created): TMPDIR=${HOME}/.bats-tmp bats <testfile>'
 
+  # LCOV_EXCL_START
   if [ -n "${DOCKER_DEFAULT_PLATFORM:-}" ]; then
     if [ "${BATS_VERBOSE_RUN:-}" = "1" ] || [ "${TEST_VORTEX_DEBUG:-}" = "1" ]; then
       echo "Using ${DOCKER_DEFAULT_PLATFORM} platform architecture."

.vortex/tooling/tests/fixtures/fixture.sh

@@ -6,3 +6,5 @@ set -eu
 curl -L -s -o /dev/null -w "%{http_code}" example.com
 
 curl example.com
+
+# LCOV_EXCL_STOP

.vortex/tooling/tests/unit/deploy-artifact.bats

@@ -1,6 +1,6 @@
 #!/usr/bin/env bats
 #
-# Test for CircleCI lifecycle.
+# Unit tests for the 'vortex-deploy-artifact' script.
 #
 # shellcheck disable=SC2030,SC2031,SC2129,SC2155,SC2034
 

.vortex/tooling/tests/unit/deploy-lagoon.bats

@@ -1,6 +1,6 @@
 #!/usr/bin/env bats
 #
-# Tests for .vortex/tooling/src/vortex-deploy-lagoon script.
+# Unit tests for the 'vortex-deploy-lagoon' script.
 #
 # shellcheck disable=SC2030,SC2031,SC2129,SC2155
 

.vortex/tooling/tests/unit/deploy-webhook.bats

@@ -1,6 +1,6 @@
 #!/usr/bin/env bats
 #
-# Test for webhook deployments.
+# Unit tests for the 'vortex-deploy-webhook' script.
 #
 # shellcheck disable=SC2030,SC2031,SC2129,SC2155
 

.vortex/tooling/tests/unit/deploy.bats

@@ -1,6 +1,6 @@
 #!/usr/bin/env bats
 #
-# Test for main deployment router script.
+# Unit tests for the 'vortex-deploy' script.
 #
 # shellcheck disable=SC2030,SC2031,SC2129,SC2155
 

.vortex/tooling/tests/unit/export-db-file.bats

@@ -1,6 +1,6 @@
 #!/usr/bin/env bats
 ##
-# Unit tests for export-db-file worker script.
+# Unit tests for the 'vortex-export-db-file' script.
 #
 # shellcheck disable=SC2030,SC2031,SC2034
 

.vortex/tooling/tests/unit/export-db.bats

@@ -1,6 +1,6 @@
 #!/usr/bin/env bats
 ##
-# Unit tests for export-db router script.
+# Unit tests for the 'vortex-export-db' script.
 #
 # shellcheck disable=SC2030,SC2031