Prevent plugin runs to use the moodle.Commenting.TodoComment sniff

A new `todo-comment-regex` option has been added to the phpcs command.

It allows to specify the regex that will be used with inspecting
todo (TODO and @todo) comments.

By default, an empty string is used for the option and that makes
the Sniff to stop checking. Whoever wants to check for anything
(tracker issue, github issue, arbitrary url, ...) can us the new
option to configure it.

Fixes #266

Author: stronk7

docs/CHANGELOG.md

@@ -9,6 +9,9 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 The format of this change log follows the advice given at [Keep a CHANGELOG](http://keepachangelog.com).
 
 ## [Unreleased]
+### Added
+- Added support for the `--todo-comment-regex` option to the `phpcs` command. When specified, all the todo comments (`TODO` and `@todo`) are inspected to ensure that they contain some text matching the regular expression (a tracker issue key: `MDL-[0-9]+`, a link to GitHub: `github.com/moodle/moodle/pull/[0-9]+`, ... or any other valid alternative).
+
 ### Changed
 - Updated project dependencies to current [moodle-cs](https://github.com/moodlehq/moodle-cs) and [moodle-local_ci](https://github.com/moodlehq/moodle-local_ci) versions.
 

docs/CLI.md

@@ -1572,7 +1572,7 @@ Run Moodle CodeSniffer standard on a plugin
 
 ### Usage
 
-* `phpcs [-s|--standard STANDARD] [-x|--exclude EXCLUDE] [--max-warnings MAX-WARNINGS] [--test-version TEST-VERSION] [--] <plugin>`
+* `phpcs [-s|--standard STANDARD] [-x|--exclude EXCLUDE] [--max-warnings MAX-WARNINGS] [--test-version TEST-VERSION] [--todo-comment-regex TODO-COMMENT-REGEX] [--] <plugin>`
 * `codechecker`
 
 Run Moodle CodeSniffer standard on a plugin
@@ -1629,6 +1629,16 @@ Version or range of version to test with PHPCompatibility
 * Is negatable: no
 * Default: `0`
 
+#### `--todo-comment-regex`
+
+Regex to use to match TODO/@todo comments
+
+* Accept value: yes
+* Is value required: yes
+* Is multiple: no
+* Is negatable: no
+* Default: `''`
+
 #### `--help|-h`
 
 Display help for the given command. When no command is given display help for the list command

src/Command/CodeCheckerCommand.php

@@ -43,7 +43,9 @@ protected function configure(): void
             ->addOption('max-warnings', null, InputOption::VALUE_REQUIRED,
                 'Number of warnings to trigger nonzero exit code - default: -1', -1)
             ->addOption('test-version', null, InputOption::VALUE_REQUIRED,
-                'Version or range of version to test with PHPCompatibility', 0);
+                'Version or range of version to test with PHPCompatibility', 0)
+            ->addOption('todo-comment-regex', null, InputOption::VALUE_REQUIRED,
+                'Regex to use to match TODO/@todo comments', '');
     }
 
     protected function initialize(InputInterface $input, OutputInterface $output): void
@@ -79,6 +81,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         // @codeCoverageIgnoreEnd
 
         $exclude = $input->getOption('exclude');
+
         $cmd     = array_merge($basicCMD, [
             '--standard=' . ($input->getOption('standard') ?: 'moodle'),
             '--extensions=php',
@@ -109,6 +112,13 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             array_push($cmd, '--runtime-set', 'testVersion', $testVersion);
         }
 
+        // Set the regex to use to match TODO/@todo comments.
+        // Note that the option defaults to an empty string,
+        // meaning that no checks will be performed. Configure it
+        // to a valid regex ('MDL-[0-9]+', 'https:', ...) to enable the checks.
+        $todoCommentRegex = $input->getOption('todo-comment-regex');
+        array_push($cmd, '--runtime-set', 'moodleTodoCommentRegex', $todoCommentRegex);
+
         // Add the files to process.
         foreach ($files as $file) {
             $cmd[] = $file;

tests/Command/CodeCheckerCommandTest.php

@@ -220,6 +220,39 @@ public function testExecuteWithExclusions()
         $this->assertSame(0, $commandTester->getStatusCode());
     }
 
+    public function testExecuteWithTodoCommentRegex()
+    {
+        // Let's add a file with some comments having links and some without
+        $content = <<<'EOT'
+            <?php
+            // phpcs:disable moodle.Files.BoilerplateComment
+            // Without any CUSTOM-[0-9]+ reference.
+
+            // TODO: This is the simplest TODO comment.
+            /** @todo This is also the simplest, but within a phpdoc block */
+            // With a CUSTOM-[0-9]+ reference.
+
+            // TODO: This is the simplest TODO comment. CUSTOM-123.
+            /** @todo This is also the simplest, but within a phpdoc block. CUSTOM-123 */
+
+            EOT;
+
+        $this->fs->dumpFile($this->pluginDir . '/test_comment_todos.php', $content);
+
+        // Without any regex configured.
+        $commandTester = $this->executeCommand($this->pluginDir);
+        $output        = $commandTester->getDisplay();
+        $this->assertMatchesRegularExpression('/\.{10} 10 \/ 10 \(100%\)/', $output);
+        $this->assertSame(0, $commandTester->getStatusCode());
+
+        // With a "CUSTOM-[0-9]+" regex configured.
+        $commandTester = $this->executeCommand($this->pluginDir, ['--todo-comment-regex' => 'CUSTOM-[0-9]+']);
+        $output        = $commandTester->getDisplay();
+        $this->assertSame(0, $commandTester->getStatusCode());
+        $this->assertMatchesRegularExpression('/FOUND 0 ERRORS AND 2 WARNINGS AFFECTING 2 LINES/', $output);
+        $this->assertMatchesRegularExpression('/Missing required "CUSTOM-\[0-9\]\+"/', $output);
+    }
+
     public function testExecuteNoFiles()
     {
         // Just random directory with no PHP files.

tests/Fixture/moodle-local_ci/lib.php

@@ -22,6 +22,12 @@
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
+// TODO: This todo comment without any MDL link is good for moodle-plugin-ci
+// (because, by default, the moodle.Commenting.TodoComment Sniff
+// isn't checked - empty todo-comment-regex option is applied). But if it's
+// set then can check for anything, like CUSTOM-123 or https://github.com
+// or whatever.
+
 /**
  * Add
  *