diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 34f83605..bdbcd609 100644 --- a/docs/CHANGELOG.md +++ b/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. diff --git a/docs/CLI.md b/docs/CLI.md index 14684a70..78282c33 100644 --- a/docs/CLI.md +++ b/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] [--] ` +* `phpcs [-s|--standard STANDARD] [-x|--exclude EXCLUDE] [--max-warnings MAX-WARNINGS] [--test-version TEST-VERSION] [--todo-comment-regex TODO-COMMENT-REGEX] [--] ` * `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 diff --git a/src/Command/CodeCheckerCommand.php b/src/Command/CodeCheckerCommand.php index bc153c62..a571f911 100644 --- a/src/Command/CodeCheckerCommand.php +++ b/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; diff --git a/tests/Command/CodeCheckerCommandTest.php b/tests/Command/CodeCheckerCommandTest.php index 85a86666..07932f85 100644 --- a/tests/Command/CodeCheckerCommandTest.php +++ b/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' + 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. diff --git a/tests/Fixture/moodle-local_ci/lib.php b/tests/Fixture/moodle-local_ci/lib.php index 5312d695..b1be3cb1 100644 --- a/tests/Fixture/moodle-local_ci/lib.php +++ b/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 *