From f06fa34611a0087de456792dc1f6f5ebf6c1e8f1 Mon Sep 17 00:00:00 2001
From: "Eloy Lafuente (stronk7)" <stronk7@moodle.org>
Date: Fri, 8 Mar 2024 10:19:22 +0100
Subject: [PATCH] Disable package checks whenever missing a target component

All the Sniffs that play with components (package, namespaces,...)
need to skip all the checks related with null components returned
by MoodleUtil::getMoodleComponent().

That happens when moodle-cs is executed against a standalone directory
that is not within a moodle structure, so it cannot find all the
component => paths mappings or a file with that structure has been
provided using the `moodleComponentsListPath` config option.

This commit just ensures that the moodle.Commenting.Package sniff
does not run any check requiring a expected component. And covers
it with tests (some checks still work, because they don't require
any expected component).
---
 moodle/Sniffs/Commenting/PackageSniff.php     |  6 +++
 .../Sniffs/Commenting/PackageSniffTest.php    | 21 +++++++++
 .../fixtures/package_tags_nocheck.php         | 47 +++++++++++++++++++
 3 files changed, 74 insertions(+)
 create mode 100644 moodle/Tests/Sniffs/Commenting/fixtures/package_tags_nocheck.php

diff --git a/moodle/Sniffs/Commenting/PackageSniff.php b/moodle/Sniffs/Commenting/PackageSniff.php
index 41867cf..c3897a1 100644
--- a/moodle/Sniffs/Commenting/PackageSniff.php
+++ b/moodle/Sniffs/Commenting/PackageSniff.php
@@ -144,6 +144,12 @@ protected function checkDocblock(
         $objectType = $this->getObjectType($phpcsFile, $stackPtr);
         $expectedPackage = MoodleUtil::getMoodleComponent($phpcsFile, true);
 
+        // Nothing to do if we have been unable to determine the package
+        // (all the following checks rely on this value).
+        if ($expectedPackage === null) {
+            return false;
+        }
+
         $packageTokens = Docblocks::getMatchingDocTags($phpcsFile, $stackPtr, '@package');
         if (empty($packageTokens)) {
             $fix = $phpcsFile->addFixableError(
diff --git a/moodle/Tests/Sniffs/Commenting/PackageSniffTest.php b/moodle/Tests/Sniffs/Commenting/PackageSniffTest.php
index 9a690a7..3b32196 100644
--- a/moodle/Tests/Sniffs/Commenting/PackageSniffTest.php
+++ b/moodle/Tests/Sniffs/Commenting/PackageSniffTest.php
@@ -29,6 +29,27 @@
  */
 class PackageSniffTest extends MoodleCSBaseTestCase
 {
+    /**
+     * Test that various checks are not performed when there isn't any component available.
+     */
+    public function testPackageOnMissingComponent(): void {
+        $this->setStandard('moodle');
+        $this->setSniff('moodle.Commenting.Package');
+        $this->setFixture(__DIR__ . '/fixtures/package_tags_nocheck.php');
+        $this->setComponentMapping([]); // No components available.
+
+        $this->setWarnings([]);
+        $this->setErrors([
+            // These are still checked because this doesn't depend on the - missing - component mapping.
+            35 => 'Missing doc comment for class missing_docblock_in_class',
+            38 => 'Missing doc comment for interface missing_docblock_in_interface',
+            41 => 'Missing doc comment for trait missing_docblock_in_trait',
+            44 => 'Missing doc comment for function missing_docblock_in_function',
+        ]);
+
+        $this->verifyCsResults();
+    }
+
     /**
      * @dataProvider packageCorrectnessProvider
      */
diff --git a/moodle/Tests/Sniffs/Commenting/fixtures/package_tags_nocheck.php b/moodle/Tests/Sniffs/Commenting/fixtures/package_tags_nocheck.php
new file mode 100644
index 0000000..79e151d
--- /dev/null
+++ b/moodle/Tests/Sniffs/Commenting/fixtures/package_tags_nocheck.php
@@ -0,0 +1,47 @@
+<?php
+
+namespace MoodleHQ\MoodleCS\moodle\Tests\Sniffs\PHPUnit;
+
+defined('MOODLE_INTERNAL') || die(); // Make this always the 1st line in all CS fixtures.
+
+// Wrong components are not reported because the expected component is needed and we don't know it
+
+/**
+ * @package wrong_package
+ */
+class package_wrong_in_class {
+}
+
+/**
+ * @package wrong_package
+ */
+interface package_wrong_in_interface {
+}
+
+/**
+ * @package wrong_package
+ */
+interface package_wrong_in_trait {
+}
+
+ /**
+ * @package wrong_package
+ */
+function package_wrong_in_function(): void {
+}
+
+// All these (missing) continue being reported because the expected component is not needed.
+
+class missing_docblock_in_class {
+}
+
+interface missing_docblock_in_interface {
+}
+
+trait missing_docblock_in_trait {
+}
+
+function missing_docblock_in_function(): void {
+    return;
+}
+