Prevent plugins to check FileExpectedTags.LicenseTagInvalid

stronk7 · stronk7 · commit 26d584c46817 · 2024-03-30T00:00:15.000+01:00
A new `license-regex` option has been added to the phpcs command. It allows to specify the regex that will be used when inspecting @license tags. By default, an empty string is used for the option and that makes the Sniff to stop checking. Whoever wants to check for anything can use the new option to configure it.
diff --git a/docs/CLI.md b/docs/CLI.md
@@ -1592,7 +1592,7 @@ Run Moodle CodeSniffer standard on a plugin
 
 ### Usage
 
-* `phpcs [-s|--standard STANDARD] [-x|--exclude EXCLUDE] [--max-warnings MAX-WARNINGS] [--test-version TEST-VERSION] [--todo-comment-regex TODO-COMMENT-REGEX] [--] <plugin>`
+* `phpcs [-s|--standard STANDARD] [-x|--exclude EXCLUDE] [--max-warnings MAX-WARNINGS] [--test-version TEST-VERSION] [--todo-comment-regex TODO-COMMENT-REGEX] [--license-regex LICENSE-REGEX] [--] <plugin>`
 * `codechecker`
 
 Run Moodle CodeSniffer standard on a plugin
@@ -1659,6 +1659,16 @@ Regex to use to match TODO/@todo comments
 * Is negatable: no
 * Default: `''`
 
+#### `--license-regex`
+
+Regex to use to match @license tags
+
+* 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
@@ -38,14 +38,43 @@ protected function configure(): void
         $this->setName('phpcs')
             ->setAliases(['codechecker'])
             ->setDescription('Run Moodle CodeSniffer standard on a plugin')
-            ->addOption('standard', 's', InputOption::VALUE_REQUIRED, 'The name or path of the coding standard to use', 'moodle')
-            ->addOption('exclude', 'x', InputOption::VALUE_REQUIRED, 'Comma separated list of sniff codes to exclude from checking', '')
-            ->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)
-            ->addOption('todo-comment-regex', null, InputOption::VALUE_REQUIRED,
-                'Regex to use to match TODO/@todo comments', '');
+            ->addOption(
+                'standard',
+                's',
+                InputOption::VALUE_REQUIRED,
+                'The name or path of the coding standard to use',
+                'moodle'
+            )->addOption(
+                'exclude',
+                'x',
+                InputOption::VALUE_REQUIRED,
+                'Comma separated list of sniff codes to exclude from checking',
+                ''
+            )->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
+            )->addOption(
+                'todo-comment-regex',
+                null,
+                InputOption::VALUE_REQUIRED,
+                'Regex to use to match TODO/@todo comments',
+                ''
+            )->addOption(
+                'license-regex',
+                null,
+                InputOption::VALUE_REQUIRED,
+                'Regex to use to match @license tags',
+                ''
+            );
     }
 
     protected function initialize(InputInterface $input, OutputInterface $output): void
@@ -119,6 +148,13 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $todoCommentRegex = $input->getOption('todo-comment-regex');
         array_push($cmd, '--runtime-set', 'moodleTodoCommentRegex', $todoCommentRegex);
 
+        // Set the regex to use to match @license tags.
+        // Note that the option defaults to an empty string,
+        // meaning that no checks will be performed. Configure it
+        // to a valid regex ('GPL-3.0', 'https:', ...) to enable the checks.
+        $licenseRegex = $input->getOption('license-regex');
+        array_push($cmd, '--runtime-set', 'moodleLicenseRegex', $licenseRegex);
+
         // Add the files to process.
         foreach ($files as $file) {
             $cmd[] = $file;
diff --git a/tests/Command/CodeCheckerCommandTest.php b/tests/Command/CodeCheckerCommandTest.php
@@ -96,13 +96,19 @@ abstract private function somefunc() { // To verify PHPCompatibility sniff.
         $output = $commandTester->getDisplay();
         $this->assertMatchesRegularExpression('/E\.* 10\.* \/ 10 \(100%\)/', $output);                // Progress.
         $this->assertMatchesRegularExpression('/\/fixable.php/', $output);                            // File.
-        $this->assertMatchesRegularExpression('/ 8 ERRORS AND 1 WARNING AFFECTING 8 /', $output);     // Summary.
+        $this->assertMatchesRegularExpression('/ 11 ERRORS AND 1 WARNING AFFECTING 8 /', $output);    // Summary.
         $this->assertMatchesRegularExpression('/moodle\.Files\.BoilerplateComment\.Wrong/', $output); // Moodle sniff.
+        $this->assertMatchesRegularExpression('/Expected MOODLE_INTERNAL check/', $output);           // Moodle sniff.
         $this->assertMatchesRegularExpression('/print_error\(\) has been deprecated/', $output);      // Moodle sniff.
+        $this->assertMatchesRegularExpression('/Usage of ELSEIF not allowed; use ELSE IF/', $output); // Squiz sniff.
         $this->assertMatchesRegularExpression('/print_object\(\) is forbidden/', $output);            // Moodle sniff.
-        $this->assertMatchesRegularExpression('/Missing doc comment for class test/', $output);       // Moodle sniff.
+        $this->assertMatchesRegularExpression('/Missing docblock for class test/', $output);          // Moodle sniff.
+        $this->assertMatchesRegularExpression('/Missing @copyright tag/', $output);                   // Moodle sniff.
+        $this->assertMatchesRegularExpression('/Missing @license tag/', $output);                     // Moodle sniff.
+        $this->assertMatchesRegularExpression('/Missing docblock for function somefunc/', $output);   // Moodle sniff.
         $this->assertMatchesRegularExpression('/AbstractPrivateMethods\.Found/', $output);    // PHPCompatibility sniff.
-        $this->assertMatchesRegularExpression('/Files\.EndFileNewline\.NotFound/', $output);          // End of file.
+        $this->assertMatchesRegularExpression('/Opening brace must be the last content/', $output);   // Generic sniff.
+        $this->assertMatchesRegularExpression('/Files\.EndFileNewline\.NotFound/', $output);          // Generic of file.
         $this->assertMatchesRegularExpression('/PHPCBF CAN FIX THE 3 MARKED SNIFF/', $output);        // PHPCBF note.
         $this->assertMatchesRegularExpression('/Time:.*Memory:/', $output);                           // Time.
 
@@ -214,27 +220,38 @@ public function testExecuteWithExclusions()
         $commandTester = $this->executeCommand($this->pluginDir);
         $output        = $commandTester->getDisplay();
         $this->assertSame(1, $commandTester->getStatusCode());
-        $this->assertMatchesRegularExpression('/FOUND 9 ERRORS AND 1 WARNING AFFECTING 1 LINE/', $output);
+        $this->assertMatchesRegularExpression('/FOUND \d+ ERRORS? AND \d+ WARNINGS? AFFECTING 1 LINE/', $output);
 
         // With exclusions.
-        $commandTester = $this->executeCommand($this->pluginDir, ['--exclude' => 'moodle.Files.RequireLogin,moodle.Files.BoilerplateComment']);
+        $commandTester = $this->executeCommand(
+            $this->pluginDir,
+            ['--exclude' => 'moodle.Files.RequireLogin,' .
+                'moodle.Files.BoilerplateComment,' .
+                'moodle.Commenting.MissingDocblock,' .
+                'moodle.Commenting.FileExpectedTags']
+        );
         $this->assertSame(0, $commandTester->getStatusCode());
     }
 
     public function testExecuteWithTodoCommentRegex()
     {
-        // Let's add a file with some comments having links and some without
+        // 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.
+
+            /**
+             * This is a nice fixture file with some todo tags.
+             *
+             * @copyright 2024 onwards Eloy Lafuente (stronk7) {@link https://stronk7.com}
+             * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+             * @todo This is also the simplest, but within a phpdoc block
+             * @todo This is also the simplest, but within a phpdoc block. CUSTOM-123
+             */
 
             // 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;
 
@@ -247,13 +264,53 @@ public function testExecuteWithTodoCommentRegex()
         $this->assertSame(0, $commandTester->getStatusCode());
 
         // With a "CUSTOM-[0-9]+" regex configured.
+        // TODO: This will start requiring complete regexp soon, see https://github.com/moodlehq/moodle-cs/issues/141
+        // (with "complete regex" meaning, with delimiters, basically).
         $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 testExecuteWithLicenseRegex()
+    {
+        // Let's add a file with some comments having various licenses.
+        $content = <<<'EOT'
+            <?php
+            // phpcs:disable moodle.Files.BoilerplateComment
+
+            /**
+             * This is a nice fixture file with some licenses.
+             *
+             * @copyright 2024 onwards Eloy Lafuente (stronk7) {@link https://stronk7.com}
+             * @license https://example.org/invented-license IL v3 or later
+             */
+
+            EOT;
+
+        $this->fs->dumpFile($this->pluginDir . '/test_comment_licenses.php', $content);
+
+        // Without any regex configured.
+        $commandTester = $this->executeCommand($this->pluginDir);
+        $output        = $commandTester->getDisplay();
+        $this->assertSame(0, $commandTester->getStatusCode());
+        $this->assertMatchesRegularExpression('/\.{10} 10 \/ 10 \(100%\)/', $output);
+
+        // With a "~v[345]] or later~" regex configured.
+        $commandTester = $this->executeCommand($this->pluginDir, ['--license-regex' => '~v[345] or later~']);
+        $output        = $commandTester->getDisplay();
+        $this->assertSame(0, $commandTester->getStatusCode());
+        $this->assertMatchesRegularExpression('/\.{10} 10 \/ 10 \(100%\)/', $output);
+
+        // With a "GNU GPL" regex configured.
+        $commandTester = $this->executeCommand($this->pluginDir, ['--license-regex' => '~GNU GPL~']);
+        $output        = $commandTester->getDisplay();
+        $this->assertSame(0, $commandTester->getStatusCode());
+        $this->assertMatchesRegularExpression('/FOUND 0 ERRORS AND 1 WARNING AFFECTING 1 LINE/', $output);
+        $this->assertMatchesRegularExpression('/Value ".+invented-license IL v3 or later" does not match/', $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
@@ -19,7 +19,7 @@
  *
  * @package   local_ci
  * @copyright Copyright (c) 2015 Blackboard Inc. (http://www.blackboard.com)
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @license   http://some.invented.license.com Not checked License v5 or later
  */
 
 // TODO: This todo comment without any MDL link is good for moodle-plugin-ci

Original file line number	Diff line number	Diff line change
`@@ -19,7 +19,7 @@`
`19`	`19`	`*`
`20`	`20`	`* @package local_ci`
`21`	`21`	`* @copyright Copyright (c) 2015 Blackboard Inc. (http://www.blackboard.com)`
`22`		`- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later`
	`22`	`+ * @license http://some.invented.license.com Not checked License v5 or later`
`23`	`23`	`*/`
`24`	`24`
`25`	`25`	`// TODO: This todo comment without any MDL link is good for moodle-plugin-ci`