PHPDoc types sniff

moodle/Tests/Sniffs/Commenting/PHPDocTypesSniffTest.php

@@ -0,0 +1,119 @@
+<?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 general right' => [
+                'fixture' => 'phpdoctypes_general_right',
+                'errors' => [],
+                'warnings' => [],
+            ],
+            'PHPDocTypes method union types right' => [
+                'fixture' => 'phpdoctypes_method_union_types_right',
+                'errors' => [],
+                'warnings' => [],
+            ],
+            'PHPDocTypes properties right' => [
+                'fixture' => 'phpdoctypes_properties_right',
+                'errors' => [],
+                'warnings' => [],
+            ],
+            'PHPDocTypes properties wrong' => [
+                'fixture' => 'phpdoctypes_properties_wrong',
+                'errors' => [
+                    33 => 'PHPDoc missing @var tag',
+                ],
+                'warnings' => [
+                    23 => 'PHPDoc variable or constant is not documented',
+                    24 => 'PHPDoc variable or constant is not documented',
+                    25 => 'PHPDoc variable or constant is not documented',
+                    26 => 'PHPDoc variable or constant is not documented',
+                    27 => 'PHPDoc variable or constant is not documented',
+                    28 => 'PHPDoc variable or constant is not documented',
+                ],
+            ],
+            'PHPDocTypes tags general right' => [
+                'fixture' => 'phpdoctypes_tags_general_right',
+                'errors' => [],
+                'warnings' => [],
+            ],
+            'PHPDocTypes tags general wrong' => [
+                'fixture' => 'phpdoctypes_tags_general_wrong',
+                'errors' => [
+                    44 => 2,
+                    54 => "PHPDoc number of function @param tags doesn't match actual number of parameters",
+                    61 => "PHPDoc number of function @param tags doesn't match actual number of parameters",
+                    71 => "PHPDoc number of function @param tags doesn't match actual number of parameters",
+                    80 => "PHPDoc number of function @param tags doesn't match actual number of parameters",
+                    90 => 'PHPDoc function parameter 2 type mismatch',
+                    100 => 'PHPDoc function parameter 1 type mismatch',
+                    110 => 'PHPDoc function parameter 1 type mismatch',
+                    120 => 'PHPDoc function parameter 2 type mismatch',
+                    129 => 'PHPDoc function return type missing or malformed',
+                ],
+                'warnings' => [
+                    110 => 'PHPDoc function parameter 2 splat mismatch',
+                ],
+            ],
+        ];
+    }
+}

moodle/Tests/Sniffs/Commenting/fixtures/phpdoctypes_general_right.php

@@ -0,0 +1,99 @@
+<?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 (or CC BY-SA v4 or later)
+ */
+
+namespace MoodleHQ\MoodleCS\moodle\Tests\Sniffs\Commenting\fixtures;
+
+defined('MOODLE_INTERNAL') || die();
+
+use stdClass as myStdClass;
+
+/**
+ * A parent class
+ */
+class php_valid_parent {
+}
+
+/**
+ * An interface
+ */
+interface php_valid_interface {
+}
+
+/**
+ * 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 (or CC BY-SA v4 or later)
+ */
+class php_valid extends php_valid_parent implements php_valid_interface {
+    /**
+     * Namespaces recognised
+     * @param \MoodleHQ\MoodleCS\moodle\Tests\Sniffs\Commenting\fixtures\php_valid $x
+     * @return void
+     */
+    function namespaces(php_valid $x): void {
+    }
+
+    /**
+     * Uses recognised
+     * @param \stdClass $x
+     * @return void
+     */
+    function uses(myStdClass $x): void {
+    }
+
+    /**
+     * Parents recognised
+     * @param php_valid $x
+     * @return void
+     */
+    function parents(php_valid_parent $x): void {
+    }
+
+    /**
+     * Interfaces recognised
+     * @param php_valid $x
+     * @return void
+     */
+    function interfaces(php_valid_interface $x): void {
+    }
+
+    /**
+     * Multiline comment
+     * @param object{
+     *   a: int,
+     *   b: string
+     * } $x
+     * @return void
+     */
+    function multiline_comment(object $x): void {
+    }
+}

moodle/Tests/Sniffs/Commenting/fixtures/phpdoctypes_method_union_types_right.php

@@ -0,0 +1,92 @@
+<?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/>.
+
+namespace MoodleHQ\MoodleCS\moodle\Tests\Sniffs\Commenting\fixtures;
+
+/**
+ * A fixture to verify various phpdoc tags in a general location.
+ *
+ * @package   local_moodlecheck
+ * @copyright 2023 Andrew Lyons <[email protected]>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class union_types {
+    /**
+     * An example of a method on a single line using union types in both the params and return values
+     * @param string|int $value
+     * @return string|int
+     */
+    public function method_oneline(string|int $value): string|int {
+        // Do something.
+        return $value;
+    }
+
+    /**
+     * An example of a method on a single line using union types in both the params and return values
+     *
+     * @param string|int $value
+     * @param int|float $othervalue
+     * @return string|int
+     */
+    public function method_oneline_multi(string|int $value, int|float $othervalue): string|int {
+        // Do something.
+        return $value;
+    }
+
+    /**
+     * An example of a method on a single line using union types in both the params and return values
+     *
+     * @param string|int $value
+     * @param int|float $othervalue
+     * @return string|int
+     */
+    public function method_multiline(
+        string|int $value,
+        int|float $othervalue,
+    ): string|int {
+        // Do something.
+        return $value;
+    }
+
+    /**
+     * An example of a method whose union values are not in the same order.
+
+     * @param int|string $value
+     * @param int|float $othervalue
+     * @return int|string
+     */
+    public function method_union_order_does_not_matter(
+        string|int $value,
+        float|int $othervalue,
+    ): string|int {
+        // Do something.
+        return $value;
+    }
+
+    /**
+     * An example of a method which uses strings, or an array of strings.
+     *
+     * @param string|string[] $arrayofstrings
+     * @return string[]|string
+     */
+    public function method_union_containing_array(
+        string|array $arrayofstrings,
+    ): string|array {
+        return [
+            'example',
+        ];
+    }
+}

moodle/Tests/Sniffs/Commenting/fixtures/phpdoctypes_properties_right.php

@@ -0,0 +1,45 @@
+<?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/>.
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * A dummy class for tests of rules involving properties.
+ */
+class dummy_with_properties {
+
+    /**
+     * @var mixed $documented1 I'm just a dummy!
+     */
+    var $documented1;
+    /**
+     * @var ?string $documented2 I'm just a dummy!
+     */
+    var mixed $documented2;
+    /**
+     * @var mixed $documented3 I'm just a dummy!
+     */
+    private $documented3;
+    /**
+     * @var ?string $documented4 I'm just a dummy!
+     */
+    private ?string $documented4;
+
+    /**
+     * @var A correctly documented constant.
+     */
+    const CORRECTLY_DOCUMENTED_CONSTANT = 0;
+}

moodle/Tests/Sniffs/Commenting/fixtures/phpdoctypes_properties_wrong.php

@@ -0,0 +1,35 @@
+<?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/>.
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * A dummy class for tests of rules involving properties.
+ */
+class dummy_with_properties {
+    var $undocumented1;
+    var ?string $undocumented2;
+    private $undocumented3;
+    private ?string $undocumented4;
+    const UNDOCUMENTED_CONSTANT1 = 0;
+    public const UNDOCUMENTED_CONSTANT2 = 0;
+
+    /**
+     * @const A wrongly documented constant.
+     */
+    const WRONGLY_DOCUMENTED_CONSTANT = 0;
+
+}