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

[AlexSkrypnyk]

Closes #3110

Summary

SchemaValidator::validate() in .vortex/installer/src/Schema/SchemaValidator.php now reads $config directly since the identity method normalizeConfig() is deleted, and .vortex/tooling/tests/_helper.bash plus six .vortex/tests/ and .vortex/tooling/tests/ scripts now pair their LCOV_EXCL_START/LCOV_EXCL_STOP coverage markers for the first time.

normalizeConfig() was documented as mapping VORTEX_INSTALLER_PROMPT_* environment variable names to handler IDs, but its body only copied $config into $normalized unchanged on every validate() call; 26 of the 40 .vortex/tooling/tests/unit/*.bats headers named a script Vortex does not ship, such as fetch-db.sh, update-vortex.sh and notify.sh on every notify-* file, instead of the extensionless vortex-* binary each test actually runs; and .vortex/tooling/tests/_helper.bash carried an LCOV_EXCL_STOP with no matching START since commit 92d66fa deleted the arm64 platform-override block the pair bracketed.

After merge, Validator::isGitRef()'s docblock lists the complete git-ref rule set including the + character the pattern already accepted, all 40 tooling BATS headers converge on # Unit tests for the '<script>' script. naming the real file under test, and HandlerInterface::discover() and resolvedMessage() describe their actual contracts instead of a nonexistent handlerManager; --prompts CLI parsing, environment discovery and file/directory discovery behave exactly as before, and .vortex/docs/content/development/variables.mdx is untouched.

Before / After

┌───────────────────────────┬──────────────────────────────┬───────────────────────────┐
│ Location                  │ Docblock said                │ Code does                 │
├───────────────────────────┼──────────────────────────────┼───────────────────────────┤
│ CustomModules::           │ .feature files whose         │ '@demo' matched anywhere  │
│ removeDemoBehatFeatures() │ FIRST LINE has '@demo'       │ in the file's contents    │
├───────────────────────────┼──────────────────────────────┼───────────────────────────┤
│ HandlerInterface::        │ The condition callback,      │ bool: TRUE to run,        │
│ shouldRun()               │ or null if not conditional   │ FALSE to skip             │
├───────────────────────────┼──────────────────────────────┼───────────────────────────┤
│ Validator::isGitRef()     │ Rule list ends mid-sentence, │ Allows '+'; rejects '..', │
│                           │ omits '+' from allowed chars │ '//', and a trailing '/'  │
└───────────────────────────┴──────────────────────────────┴───────────────────────────┘

SchemaValidator::validate() call path

Before:
  validate($config)
  ├─ normalizeConfig($config)
  │    └─ foreach ($config as $key => $value) { $normalized[$key] = $value; }   (identity, no-op)
  ├─ foreach (array_keys($normalized) as $key) { ... }
  └─ checkDependency($depends_on, $normalized)

After:
  validate($config)
  ├─ foreach (array_keys($config) as $key) { ... }
  └─ checkDependency($depends_on, $config)

Changes

• .vortex/installer/src/Command/InstallCommand.php: removed the stray Run command. summary line above Install command., matching BuildCommand and CheckRequirementsCommand.
• .vortex/installer/src/Utils/Validator.php, .vortex/installer/src/Utils/Normalizer.php: deleted class docblocks copied from other classes (Converter./Convert strings to different formats. and Installer configuration./Installer config is a config of this installer script.); Drupal.Commenting.ClassComment is excluded in .vortex/installer/phpcs.xml and 8 of the 16 Utils/ classes already carry no class docblock.
• .vortex/installer/src/Prompts/Handlers/HandlerInterface.php: shouldRun()'s @return now describes its bool result instead of a nonexistent condition callback; discover()'s summary and @return now cover discovery from composer.json, .env, files and directories, not only environment variables; resolvedMessage()'s reference to a nonexistent handlerManager and the garbled "handlering" are removed.
• .vortex/installer/src/Prompts/Handlers/CustomModules.php: removeDemoBehatFeatures()'s docblock now says the @demo tag is matched anywhere in a .feature file's contents, matching what File::findContainingInDir() does.
• .vortex/installer/src/Prompts/PromptManager.php: runPrompts() now says each prompt returns its default in non-interactive mode; resolvePromptOverrides() drops the claim that it normalizes keys to handler IDs and the inline comment claiming $raw reads resolved defaults for missing prompts; args() drops an orphaned The handler id. line left under the @param $handler_class tag.
• .vortex/installer/src/Utils/OptionsResolver.php: resolve()'s docblock now says each installer variable is resolved from the CLI options, the --config JSON and the environment, replacing the claim that values come from $this->config->get() alone.
• .vortex/installer/src/Utils/Git.php: listRemotes()'s inline comment now says the trailing (fetch)/(push) suffix is stripped from $parts[1], the remote URL, not from the remote name.
• .vortex/installer/src/Utils/FileManager.php: removeObsoletePaths()'s docblock drops the sentence describing that it runs after copyFiles(), keeping the docblock caller-agnostic.
• .vortex/installer/src/Utils/Validator.php: isGitRef()'s rule list is completed (adds + to the allowed characters, adds the ..////trailing-/ rejections) and the duplicate six-line inline comment restating the same rules is deleted.
• .vortex/installer/src/Schema/SchemaValidator.php: deletes normalizeConfig(); validate() iterates $config directly and passes it to checkDependency(), whose @param now describes "The config array, keyed by handler ID" instead of "The normalized config".
• .vortex/installer/tests/Unit/Utils/EnvTest.php, .vortex/installer/tests/Unit/Utils/ValidatorTest.php: deleted class docblocks naming InstallerDotEnvTest/InstallerHelpersTest, classes that do not exist in these files, matching the other 10 classes in tests/Unit/Utils/ that already carry no class docblock.
• .vortex/installer/tests/Functional/Command/BuildCommandTest.php: the data-provider docblock now names testBuildCommand, the method that consumes it, instead of testBuildWithMockedRunner.
• .vortex/tooling/tests/unit/*.bats (40 files): every header now names the script the file actually executes and converges on # Unit tests for the '<script>' script.; provision-*.bats and post-coverage-comment.bats already named real files and keep their subject.
• .vortex/tooling/src/vortex-doctor: usage lines cite vortex-doctor and vortex-doctor info instead of doctor.sh.
• .vortex/tooling/src/vortex-notify-email: the description line states the send mechanism (sendmail or mail) instead of repeating the summary, and the usage line cites vortex-notify-email instead of ./notify-email.
• .vortex/tooling/tests/_helper.bash: restores the LCOV_EXCL_START above the DOCKER_DEFAULT_PLATFORM reporting branch, pairing it with the LCOV_EXCL_STOP orphaned when commit 92d66fa removed the arm64 override block.
• .vortex/tests/lint.ci.sh, lint.dockerfiles.sh, lint.markdown.sh, lint.scripts.sh, test.common.sh, .vortex/tooling/tests/fixtures/fixture.sh: each closes its whole-file LCOV_EXCL_START with a trailing LCOV_EXCL_STOP.

Verification

• .vortex/installer: composer lint (phpcs, phpstan, rector) exit 0; composer test green, 1658 tests / 5490 assertions.
• .vortex: ahoy lint-scripts exit 0; ahoy test-bats tooling/tests/unit exit 0, 338 tests.
• ahoy update-docs regenerates no changes, so .vortex/docs/content/development/variables.mdx is unaffected.

[coderabbitai]

Warning

Review limit reached

• Run on-demand review

_{On-demand reviews are free for the next 12 days. After that, they cost $0.25 per reviewed file.}

Or wait 34 minutes for your next included review.

Check out review usage here.

View limit details

Limit details: You’ve used all 2 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Team

Run ID: e1309e00-1a2d-4542-bd70-a2c8585db5eb

📥 Commits

Reviewing files that changed from the base of the PR and between d131ccb and 9472cca.

📒 Files selected for processing (62)

• .vortex/installer/src/Command/InstallCommand.php
• .vortex/installer/src/Prompts/Handlers/CustomModules.php
• .vortex/installer/src/Prompts/Handlers/HandlerInterface.php
• .vortex/installer/src/Prompts/PromptManager.php
• .vortex/installer/src/Schema/SchemaValidator.php
• .vortex/installer/src/Utils/FileManager.php
• .vortex/installer/src/Utils/Git.php
• .vortex/installer/src/Utils/Normalizer.php
• .vortex/installer/src/Utils/OptionsResolver.php
• .vortex/installer/src/Utils/Validator.php
• .vortex/installer/tests/Functional/Command/BuildCommandTest.php
• .vortex/installer/tests/Unit/Utils/EnvTest.php
• .vortex/installer/tests/Unit/Utils/ValidatorTest.php
• .vortex/tests/lint.ci.sh
• .vortex/tests/lint.dockerfiles.sh
• .vortex/tests/lint.markdown.sh
• .vortex/tests/lint.scripts.sh
• .vortex/tests/test.common.sh
• .vortex/tooling/src/vortex-doctor
• .vortex/tooling/src/vortex-notify-email
• .vortex/tooling/tests/_helper.bash
• .vortex/tooling/tests/fixtures/fixture.sh
• .vortex/tooling/tests/unit/deploy-artifact.bats
• .vortex/tooling/tests/unit/deploy-lagoon.bats
• .vortex/tooling/tests/unit/deploy-webhook.bats
• .vortex/tooling/tests/unit/deploy.bats
• .vortex/tooling/tests/unit/export-db-file.bats
• .vortex/tooling/tests/unit/export-db.bats
• .vortex/tooling/tests/unit/fetch-db-acquia.bats
• .vortex/tooling/tests/unit/fetch-db-container-registry.bats
• .vortex/tooling/tests/unit/fetch-db-ftp.bats
• .vortex/tooling/tests/unit/fetch-db-lagoon.bats
• .vortex/tooling/tests/unit/fetch-db-s3.bats
• .vortex/tooling/tests/unit/fetch-db-url.bats
• .vortex/tooling/tests/unit/fetch-db.bats
• .vortex/tooling/tests/unit/helpers.bats
• .vortex/tooling/tests/unit/import-db-file.bats
• .vortex/tooling/tests/unit/import-db.bats
• .vortex/tooling/tests/unit/login-container-registry.bats
• .vortex/tooling/tests/unit/notify-diffy.bats
• .vortex/tooling/tests/unit/notify-email.bats
• .vortex/tooling/tests/unit/notify-github.bats
• .vortex/tooling/tests/unit/notify-jira.bats
• .vortex/tooling/tests/unit/notify-newrelic.bats
• .vortex/tooling/tests/unit/notify-slack.bats
• .vortex/tooling/tests/unit/notify-webhook.bats
• .vortex/tooling/tests/unit/notify.bats
• .vortex/tooling/tests/unit/post-coverage-comment.bats
• .vortex/tooling/tests/unit/provision-enable-demo-modules.bats
• .vortex/tooling/tests/unit/provision-enable-dev-modules.bats
• .vortex/tooling/tests/unit/provision-example.bats
• .vortex/tooling/tests/unit/provision-migration.bats
• .vortex/tooling/tests/unit/provision-search-index.bats
• .vortex/tooling/tests/unit/provision.bats
• .vortex/tooling/tests/unit/push-container-registry.bats
• .vortex/tooling/tests/unit/push-db-image.bats
• .vortex/tooling/tests/unit/push-db-s3.bats
• .vortex/tooling/tests/unit/reset.bats
• .vortex/tooling/tests/unit/setup-ssh.bats
• .vortex/tooling/tests/unit/task-purge-cache-acquia.bats
• .vortex/tooling/tests/unit/task.bats
• .vortex/tooling/tests/unit/update-vortex.bats

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Code coverage (threshold: 90%)

  Classes: 100.00% (1/1)
  Methods: 100.00% (2/2)
  Lines:   98.68% (224/227)

Per-class coverage

Drupal\ys_demo\Plugin\Block\CounterBlock
  Methods: 100.00% ( 2/ 2)   Lines: 100.00% ( 10/ 10)

[AlexSkrypnyk]

Code coverage (threshold: 90%)

  Classes: 100.00% (1/1)
  Methods: 100.00% (2/2)
  Lines:   98.68% (224/227)

Per-class coverage

Drupal\ys_demo\Plugin\Block\CounterBlock
  Methods: 100.00% ( 2/ 2)   Lines: 100.00% ( 10/ 10)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.79%. Comparing base (d131ccb) to head (9472cca).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3123      +/-   ##
==========================================
- Coverage   87.13%   86.79%   -0.35%     
==========================================
  Files         108      101       -7     
  Lines        5169     4998     -171     
  Branches       49        3      -46     
==========================================
- Hits         4504     4338     -166     
+ Misses        665      660       -5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

📖 Documentation preview for this pull request has been deployed to Netlify:

https://6aa0a181016a895b4e03575d--vortex-docs.netlify.app

This preview is rebuilt on every commit and is not the production documentation site.