CONTRIB-8920 moodle-cs: Deprecation alerts for capabilities

moodle/Sniffs/Access/DeprecatedCapabilitySniff.php

@@ -0,0 +1,111 @@
+<?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/>.
+
+/**
+ * Checks that each file contains necessary login checks.
+ *
+ * @package    local_codechecker
+ * @copyright  2022 Laurent David <laurent.david@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace MoodleCodeSniffer\moodle\Sniffs\Access;
+
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\Sniff;
+
+class DeprecatedCapabilitySniff implements Sniff {
+
+    // phpcs:disable moodle.NamingConventions.ValidVariableName.MemberNameUnderscore
+    /**
+     * If we try to check this capability, a warning will be shown.
+     *
+     * @var array
+     */
+    public $capabilitiesWarningList = [];
+
+    /**
+     * If we try to check this capability, an error will be shown.
+     *
+     * @var array
+     */
+    public $capabilitiesErrorList = [];
+
+    // phpcs:enable
+
+    /**
+     * Access function type
+     *
+     * @var string[]
+     */
+    public $accessfunctions = ['has_access', 'has_capability'];
+
+    /**
+     * Register for open tag (only process once per file).
+     */
+    public function register() {
+        return array(T_OPEN_PARENTHESIS);
+    }
+
+    /**
+     * Processes php files and for required login checks if includeing config.php
+     *
+     * @param File $file The file being scanned.
+     * @param int $stackptr The position in the stack.
+     */
+    public function process(File $file, $stackptr) {
+        $functionnamepos = $file->findPrevious(T_STRING, $stackptr - 1);
+        if ($functionnamepos === false) {
+            return;
+        }
+        $tokens = $file->getTokens();
+        if (empty($tokens[$functionnamepos]) || !$this->is_an_access_function($tokens[$functionnamepos])) {
+            return;
+        }
+
+        $alldeprecated = array_merge($this->capabilitiesErrorList, $this->capabilitiesWarningList);
+        $closeparenthesispos = $file->findNext(T_CLOSE_PARENTHESIS, $stackptr + 1);
+        if ($closeparenthesispos === false) {
+            // Live coding, parse error or not a function call.
+            return;
+        }
+        $closeparenthesistoken = $tokens[$closeparenthesispos];
+        $starttoken = $closeparenthesistoken['parenthesis_opener'] + 1;
+        $endtoken = $closeparenthesistoken['parenthesis_closer'];
+        $values = $file->getTokensAsString($starttoken, $endtoken - $starttoken);
+        foreach ($alldeprecated as $capability) {
+            if (strpos($values, $capability) !== false) {
+                if (in_array($capability, $this->capabilitiesWarningList)) {
+                    $file->addWarning("The following capability '$capability' will be deprecated soon.", $starttoken,
+                        'DeprecatedCapability');
+                } else {
+                    $file->addError("The following capability '$capability' has been deprecated.", $starttoken,
+                        'DeprecatedCapability');
+                }
+            }
+        }
+    }
+
+    /**
+     * Is the current name an access function
+     *
+     * @param array $token current token
+     * @return bool true if the current methodname is access function.
+     */
+    protected function is_an_access_function(array $token) {
+        return in_array($token['content'], $this->accessfunctions);
+    }
+}

moodle/ruleset.xml

@@ -87,6 +87,15 @@
         <severity>0</severity>
     </rule>
 
+    <!-- Setup deprecated capability list -->
+    <rule ref="moodle.Access.DeprecatedCapability">
+        <properties>
+            <!--            <property name="capabilitiesWarningList"  type="array">-->
+            <!--                <element value="moodle/course:useremail"/>-->
+            <!--            </property>-->
+        </properties>
+    </rule>
+
     <!-- Let's add the complete PHPCompatibility standard -->
     <rule ref="PHPCompatibility" />
 

moodle/tests/fixtures/moodle_access.php

@@ -0,0 +1,8 @@
+<?php
+defined('MOODLE_INTERNAL') || die(); // Make this always the 1st line in all CS fixtures.
+$context = context_system::instance();
+// phpcs:set moodle.Access.DeprecatedCapability capabilitiesWarningList[] moodle/course:useremail
+// phpcs:set moodle.Access.DeprecatedCapability capabilitiesErrorList[] moodle/site:useremail
+has_capability('moodle/course:useremail', $context);
+has_capability('moodle/site:useremail', $context);
+

moodle/tests/moodlestandard_test.php

@@ -956,4 +956,29 @@ public function test_moodle_files_requirelogin_nomoodlecookies_ok() {
 
         $this->verify_cs_results();
     }
+
+    /**
+     * Test the moodle.Access.DeprecatedCapabilitySniff sniff.
+     *
+     *
+     * @covers \MoodleCodeSniffer\moodle\Sniffs\Access\DeprecatedCapabilitySniff
+     */
+    public function test_moodle_deprecated_access() {
+
+        // Define the standard, sniff and fixture to use.
+        $this->set_standard('moodle');
+        $this->set_sniff('moodle.Access.DeprecatedCapability');
+        $this->set_fixture(__DIR__ . '/fixtures/moodle_access.php');
+        // Define expected results (errors and warnings). Format, array of:
+        // - line => problem.
+        $this->set_errors([
+            7 => 'The following capability \'moodle/site:useremail\' has been deprecated',
+        ]);
+        $this->set_warnings([
+            6 => 'The following capability \'moodle/course:useremail\' will be deprecated soon',
+        ]);
+
+        // Let's do all the hard work!
+        $this->verify_cs_results();
+    }
 }