PHPDoc types sniff

moodle/Tests/Sniffs/Commenting/PHPDocTypesSniffTest.php

@@ -0,0 +1,145 @@
+<?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\Sniffs\Commenting;
+
+use MoodleHQ\MoodleCS\moodle\Tests\MoodleCSBaseTestCase;
+
+/**
+ * Test the PHPDocTypes sniff.
+ *
+ * @author     James Calder
+ * @copyright  based on work by 2024 onwards Andrew Lyons <[email protected]>
+ * @license    https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * @covers \MoodleHQ\MoodleCS\moodle\Sniffs\Commenting\PHPDocTypesSniff
+ */
+class PHPDocTypesSniffTest extends MoodleCSBaseTestCase
+{
+    /**
+     * @dataProvider provider
+     * @param string $fixture
+     * @param array $errors
+     * @param array $warnings
+     */
+    public function testPHPDocTypesCorrectness(
+        string $fixture,
+        array $errors,
+        array $warnings
+    ): void {
+        $this->setStandard('moodle');
+        $this->setSniff('moodle.Commenting.PHPDocTypes');
+        $this->setFixture(sprintf("%s/fixtures/%s.php", __DIR__, $fixture));
+        $this->setWarnings($warnings);
+        $this->setErrors($errors);
+        /*$this->setApiMappings([
+            'test' => [
+                'component' => 'core',
+                'allowspread' => true,
+                'allowlevel2' => false,
+            ],
+        ]);*/
+
+        $this->verifyCsResults();
+    }
+
+    /**
+     * @return array
+     */
+    public static function provider(): array {
+        return [
+            'PHPDocTypes complex warn' => [
+                'fixture' => 'phpdoctypes/phpdoctypes_complex_warn',
+                'errors' => [],
+                'warnings' => [
+                    39 => "PHPDoc template type doesn't conform to PHP-FIG PHPDoc",
+                    40 => "PHPDoc class property type doesn't conform to PHP-FIG PHPDoc",
+                    45 => "PHPDoc function parameter type doesn't conform to PHP-FIG PHPDoc",
+                    46 => "PHPDoc function return type doesn't conform to PHP-FIG PHPDoc",
+                    52 => "PHPDoc var type doesn't conform to PHP-FIG PHPDoc",
+                    57 => "PHPDoc var type doesn't conform to PHP-FIG PHPDoc",
+                ],
+            ],
+            /*'PHPDocTypes docs missing warn' => [
+                'fixture' => 'phpdoctypes/phpdoctypes_docs_missing_warn',
+                'errors' => [],
+                'warnings' => [
+                    40 => "PHPDoc function is not documented",
+                    43 => 2,
+                    52 => "PHPDoc variable or constant is not documented",
+                    54 => "PHPDoc variable missing @var tag",
+                ],
+            ],*/
+            'PHPDocTypes general right' => [
+                'fixture' => 'phpdoctypes/phpdoctypes_general_right',
+                'errors' => [],
+                'warnings' => [],
+            ],
+            'PHPDocTypes general wrong' => [
+                'fixture' => 'phpdoctypes/phpdoctypes_general_wrong',
+                'errors' => [
+                    41 => "PHPDoc class property type missing or malformed",
+                    42 => "PHPDoc class property name missing or malformed",
+                    48 => "PHPDoc function parameter type missing or malformed",
+                    49 => "PHPDoc function parameter name missing or malformed",
+                    50 => "PHPDoc function parameter doesn't exist",
+                    52 => "PHPDoc function parameter repeated",
+                    53 => "PHPDoc function parameter type mismatch",
+                    64 => "PHPDoc multiple function @return tags--Put in one tag, seperated by vertical bars |",
+                    72 => "PHPDoc function return type missing or malformed",
+                    79 => "PHPDoc function return type mismatch",
+                    87 => "PHPDoc template name missing or malformed",
+                    88 => "PHPDoc template type missing or malformed",
+                    94 => "PHPDoc var type missing or malformed",
+                    97 => "PHPDoc var type mismatch",
+                    102 => "PHPDoc var type missing or malformed",
+                ],
+                'warnings' => [
+                    31 => "PHPDoc misplaced tag",
+                    46 => "PHPDoc function parameter order wrong",
+                    54 => "PHPDoc function parameter splat mismatch",
+                ],
+            ],
+            'PHPDocTypes namespace right' => [
+                'fixture' => 'phpdoctypes/phpdoctypes_namespace_right',
+                'errors' => [],
+                'warnings' => [],
+            ],
+            'PHPDocTypes parse wrong' => [
+                'fixture' => 'phpdoctypes/phpdoctypes_parse_wrong',
+                'errors' => [
+                    91 => "PHPDoc function parameter type mismatch",
+                ],
+                'warnings' => [],
+            ],
+            'PHPDocTypes style warn' => [
+                'fixture' => 'phpdoctypes/phpdoctypes_style_warn',
+                'errors' => [],
+                'warnings' => [
+                    36 => "PHPDoc class property type doesn't conform to recommended style",
+                    41 => "PHPDoc function parameter type doesn't conform to recommended style",
+                    42 => "PHPDoc function return type doesn't conform to recommended style",
+                    43 => "PHPDoc tempate type doesn't conform to recommended style",
+                    49 => "PHPDoc var type doesn't conform to recommended style",
+                    52 => "PHPDoc var type doesn't conform to recommended style",
+                    56 => "PHPDoc var type doesn't conform to recommended style",
+                    63 => "PHPDoc var type doesn't conform to recommended style",
+                ],
+            ],
+        ];
+    }
+}

moodle/Tests/Sniffs/Commenting/fixtures/phpdoctypes/phpdoctypes_complex_warn.php

@@ -0,0 +1,58 @@
+<?php
+// This file is part of Moodle - http://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 <http://www.gnu.org/licenses/>.
+
+/**
+ * A collection of valid types for testing
+ *
+ * This file should have no errors when checked with either PHPStan or Psalm.
+ * Having just valid code in here means it can be easily checked with other checkers,
+ * to verify we are actually checking against correct examples.
+ *
+ * @package   local_codechecker
+ * @copyright 2024 Otago Polytechnic
+ * @author    James Calder
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later, CC BY-SA v4 or later, and BSD-3-Clause
+ */
+
+namespace MoodleHQ\MoodleCS\moodle\Tests\Sniffs\Commenting\fixtures;
+
+/**
+ * A collection of valid types for testing
+ *
+ * @package   local_codechecker
+ * @copyright 2023 Otago Polytechnic
+ * @author    James Calder
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later, CC BY-SA v4 or later, and BSD-3-Clause
+ * @template  T of ?int
+ * @property ?int $p
+ */
+class php_valid {
+
+    /**
+     * @param ?int $p
+     * @return ?int
+     */
+    function f(?int $p): ?int {
+        return $p;
+    }
+
+    /** @var ?int */
+    public ?int $v;
+
+}
+
+/** @var ?int */
+$v2 = 0;

moodle/Tests/Sniffs/Commenting/fixtures/phpdoctypes/phpdoctypes_docs_missing_warn.php

@@ -0,0 +1,57 @@
+<?php
+// This file is part of Moodle - http://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 <http://www.gnu.org/licenses/>.
+
+/**
+ * A collection code with missing annotations for testing
+ *
+ * These should pass PHPStan and Psalm.
+ * But warnings should be given by the PHPDocTypesSniff when CHECK_HAS_DOCS is enabled.
+ *
+ * @package   local_codechecker
+ * @copyright 2024 Otago Polytechnic
+ * @author    James Calder
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later, CC BY-SA v4 or later, and BSD-3-Clause
+ */
+
+/**
+ * A collection of code with missing annotations for testing
+ *
+ * @package   local_codechecker
+ * @copyright 2024 Otago Polytechnic
+ * @author    James Calder
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later, CC BY-SA v4 or later, and BSD-3-Clause
+ */
+class types_invalid {
+
+    // PHPDoc function is not documented
+    public function fun_not_doc(int $p): void {
+    }
+
+    /**
+     * PHPDoc function parameter $p not documented
+     * PHPDoc missing function @return tag
+     */
+    public function fun_missing_param_ret(int $p): int {
+        return $p;
+    }
+
+    // PHPDoc variable or constant is not documented
+    public int $v1 = 0;
+
+    /** PHPDoc missing @var tag */
+    public int $v2 = 0;
+
+}