From 237cf60e5157e7cee3b624ae1bd25df13fb0da14 Mon Sep 17 00:00:00 2001
From: Andrew Nicols <andrew@nicols.co.uk>
Date: Wed, 13 Mar 2024 23:38:13 +0800
Subject: [PATCH] Move getObject* helpers to their own Util

---
 moodle/Sniffs/Commenting/PackageSniff.php |  43 +--------
 moodle/Tests/Util/TokenUtilTest.php       | 106 ++++++++++++++++++++++
 moodle/Util/TokenUtil.php                 |  61 +++++++++++++
 3 files changed, 170 insertions(+), 40 deletions(-)
 create mode 100644 moodle/Tests/Util/TokenUtilTest.php
 create mode 100644 moodle/Util/TokenUtil.php

diff --git a/moodle/Sniffs/Commenting/PackageSniff.php b/moodle/Sniffs/Commenting/PackageSniff.php
index c3897a1..3f244ef 100644
--- a/moodle/Sniffs/Commenting/PackageSniff.php
+++ b/moodle/Sniffs/Commenting/PackageSniff.php
@@ -19,9 +19,9 @@
 
 use MoodleHQ\MoodleCS\moodle\Util\MoodleUtil;
 use MoodleHQ\MoodleCS\moodle\Util\Docblocks;
+use MoodleHQ\MoodleCS\moodle\Util\Tokens;
 use PHP_CodeSniffer\Sniffs\Sniff;
 use PHP_CodeSniffer\Files\File;
-use PHPCSUtils\Utils\ObjectDeclarations;
 
 /**
  * Checks that all test classes and global functions have appropriate @package tags.
@@ -89,43 +89,6 @@ public function process(File $phpcsFile, $stackPtr) {
         }
     }
 
-    /**
-     * Get the human-readable object type.
-     *
-     * @param File $phpcsFile
-     * @param int $stackPtr
-     * @return string
-     */
-    protected function getObjectType(
-        File $phpcsFile,
-        int $stackPtr
-    ): string {
-        $tokens = $phpcsFile->getTokens();
-        if ($tokens[$stackPtr]['code'] === T_OPEN_TAG) {
-            return 'file';
-        }
-        return $tokens[$stackPtr]['content'];
-    }
-
-    /**
-     * Get the human readable object name.
-     *
-     * @param File $phpcsFile
-     * @param int $stackPtr
-     * @return string
-     */
-    protected function getObjectName(
-        File $phpcsFile,
-        int $stackPtr
-    ): string {
-        $tokens = $phpcsFile->getTokens();
-        if ($tokens[$stackPtr]['code'] === T_OPEN_TAG) {
-            return basename($phpcsFile->getFilename());
-        }
-
-        return ObjectDeclarations::getName($phpcsFile, $stackPtr);
-    }
-
     /**
      * Check the docblock for a @package tag.
      *
@@ -140,8 +103,8 @@ protected function checkDocblock(
         array $docblock
     ): bool {
         $tokens = $phpcsFile->getTokens();
-        $objectName = $this->getObjectName($phpcsFile, $stackPtr);
-        $objectType = $this->getObjectType($phpcsFile, $stackPtr);
+        $objectName = Tokens::getObjectName($phpcsFile, $stackPtr);
+        $objectType = Tokens::getObjectType($phpcsFile, $stackPtr);
         $expectedPackage = MoodleUtil::getMoodleComponent($phpcsFile, true);
 
         // Nothing to do if we have been unable to determine the package
diff --git a/moodle/Tests/Util/TokenUtilTest.php b/moodle/Tests/Util/TokenUtilTest.php
new file mode 100644
index 0000000..d32e537
--- /dev/null
+++ b/moodle/Tests/Util/TokenUtilTest.php
@@ -0,0 +1,106 @@
+<?php
+
+// This file is part of Moodle - https://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <https://www.gnu.org/licenses/>.
+
+namespace MoodleHQ\MoodleCS\moodle\Tests\Util;
+
+use MoodleHQ\MoodleCS\moodle\Tests\MoodleCSBaseTestCase;
+use MoodleHQ\MoodleCS\moodle\Util\TokenUtil;
+use PHP_CodeSniffer\Config;
+use PHP_CodeSniffer\Ruleset;
+use PHP_CodeSniffer\Files\DummyFile;
+
+/**
+ * Test the Tokens specific utilities class
+ *
+ * @copyright  2021 onwards Eloy Lafuente (stronk7) {@link https://stronk7.com}
+ * @license    https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * @covers \MoodleHQ\MoodleCS\moodle\Util\TokenUtil
+ */
+class TokenUtilTest extends MoodleCSBaseTestCase
+{
+    /**
+     * @dataProvider objectPropertiesProvider
+     */
+    public function testGetObjectProperties(
+        string $content,
+        int $type,
+        string $expectedType,
+        string $expectedName
+    ): void {
+        $config = new Config([]);
+        $ruleset = new Ruleset($config);
+
+        $phpcsFile = new DummyFile($content, $ruleset, $config);
+        $phpcsFile->process();
+
+        $stackPtr = $phpcsFile->findNext($type, 0);
+
+        $this->assertEquals($expectedType, TokenUtil::getObjectType($phpcsFile, $stackPtr));
+        $this->assertEquals($expectedName, TokenUtil::getObjectName($phpcsFile, $stackPtr));
+    }
+
+    public static function objectPropertiesProvider(): array {
+        $cases = [
+            'Class name' => [
+                '<?php class Example {}',
+                T_CLASS,
+                'class',
+                'Example',
+            ],
+            'File name' => [
+                // Setting the first line of the file to phpcs_input_file: pathname will set the file name of the dummy file.
+                <<<EOF
+                phpcs_input_file: /path/to/file/example.php
+                <?php class Example {}
+                EOF,
+                T_OPEN_TAG,
+                'file',
+                'example.php',
+            ],
+            'Trait name' => [
+                '<?php trait ExampleTrait {}',
+                T_TRAIT,
+                'trait',
+                'ExampleTrait',
+            ],
+            'Interface name' => [
+                '<?php interface ExampleInterface {}',
+                T_INTERFACE,
+                'interface',
+                'ExampleInterface',
+            ],
+            'Function name' => [
+                '<?php function exampleFunction(): void {}',
+                T_FUNCTION,
+                'function',
+                'exampleFunction',
+            ],
+        ];
+
+        if (version_compare(PHP_VERSION, '8.1.0') >= 0) {
+            $cases['Enum name'] = [
+                '<?php enum ExampleEnum {}',
+                T_ENUM,
+                'enum',
+                'ExampleEnum',
+            ];
+        }
+
+        return $cases;
+    }
+}
diff --git a/moodle/Util/TokenUtil.php b/moodle/Util/TokenUtil.php
new file mode 100644
index 0000000..6fe38ad
--- /dev/null
+++ b/moodle/Util/TokenUtil.php
@@ -0,0 +1,61 @@
+<?php
+
+// This file is part of Moodle - https://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <https://www.gnu.org/licenses/>.
+
+namespace MoodleHQ\MoodleCS\moodle\Util;
+
+use PHP_CodeSniffer\Files\File;
+use PHPCSUtils\Utils\ObjectDeclarations;
+
+class TokenUtil
+{
+    /**
+     * Get the human-readable object type.
+     *
+     * @param File $phpcsFile
+     * @param int $stackPtr
+     * @return string
+     */
+    public static function getObjectType(
+        File $phpcsFile,
+        int $stackPtr
+    ): string {
+        $tokens = $phpcsFile->getTokens();
+        if ($tokens[$stackPtr]['code'] === T_OPEN_TAG) {
+            return 'file';
+        }
+        return $tokens[$stackPtr]['content'];
+    }
+
+    /**
+     * Get the human readable object name.
+     *
+     * @param File $phpcsFile
+     * @param int $stackPtr
+     * @return string
+     */
+    public static function getObjectName(
+        File $phpcsFile,
+        int $stackPtr
+    ): string {
+        $tokens = $phpcsFile->getTokens();
+        if ($tokens[$stackPtr]['code'] === T_OPEN_TAG) {
+            return basename($phpcsFile->getFilename());
+        }
+
+        return ObjectDeclarations::getName($phpcsFile, $stackPtr);
+    }
+}