Merge pull request moodlehq#267 from stronk7/prevent_todo_sniff_for_p…

…lugins

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

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
  *