Implement getRequiredFunctionCalls check and use it in filter plugin validation.

This address scenario where file is supposed to contain certain function
call, such as `class_alias` in Filter plugin type backward compatibility
support per https://moodledev.io/docs/4.5/devupdate#filter-plugins

The patch makes possible for deleveloper to specify:
* getRequiredFunctionCalls to make sure file contains function call as
  name suggests.
* FileTokens::notFoundHint to give some context for requirement to improve developer experience. This works with FileTokens in any other validation methods.

Author: kabalin

.php-cs-fixer.cache

@@ -9,8 +9,14 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 The format of this change log follows the advice given at [Keep a CHANGELOG](https://keepachangelog.com).
 
 ## [Unreleased]
+### Added
+- Improvements to plugin validation implementation:
+    `getRequiredFunctionCalls` in plugin type specific `Requirements` class can be used to validate that file contains function call.
+    `FileTokens::notFoundHint` can be used to give some context for validation error to improve developer experience.
+
 ### Fixed
 - Fixed stylelinting error in non-theme plugins containing scss.
+- Updated filter plugin validation requirements to comply with Moodle 4.5
 
 ### Removed
 - Stylelint less component task (`grunt stylelint:less`) has been deprecated in

.phpunit.result.cache

@@ -14,9 +14,11 @@
 
 use PhpParser\Node\Expr\Array_;
 use PhpParser\Node\Expr\Assign;
+use PhpParser\Node\Expr\FuncCall;
 use PhpParser\Node\Expr\PropertyFetch;
 use PhpParser\Node\Expr\Variable;
 use PhpParser\Node\Identifier;
+use PhpParser\Node\Name;
 use PhpParser\Node\Scalar\String_;
 use PhpParser\Node\Stmt;
 use PhpParser\Node\Stmt\Class_;
@@ -116,6 +118,26 @@ public function filterAssignments(array $statements): array
         return $assigns;
     }
 
+    /**
+     * Extract all the function call expressions from the statements.
+     *
+     * @param Stmt[] $statements
+     *
+     * @return FuncCall[]
+     */
+    public function filterFunctionCalls(array $statements): array
+    {
+        $calls = [];
+        foreach ($statements as $statement) {
+            // Only expressions that are function calls.
+            if ($statement instanceof Expression && $statement->expr instanceof FuncCall) {
+                $calls[] = $statement->expr;
+            }
+        }
+
+        return $calls;
+    }
+
     /**
      * Find first variable assignment with a given name.
      *

docs/CHANGELOG.md

@@ -29,6 +29,13 @@ class FileTokens
      */
     public string $file;
 
+    /**
+     * Not found error hint.
+     *
+     * @var string
+     */
+    public string $hint = '';
+
     /**
      * @param string $file
      */
@@ -59,6 +66,16 @@ public function hasTokens(): bool
         return !empty($this->tokens);
     }
 
+    /**
+     * Do we have any hint?
+     *
+     * @return bool
+     */
+    public function hasHint(): bool
+    {
+        return !empty($this->hint);
+    }
+
     /**
      * @param Token $token
      *
@@ -166,4 +183,18 @@ public function resetTokens(): void
             $token->reset();
         }
     }
+
+    /**
+     * Not found error additional information guiding user how to fix it (optional).
+     *
+     * @param string $hint
+     *
+     * @return self
+     */
+    public function notFoundHint(string $hint): self
+    {
+        $this->hint = $hint;
+
+        return $this;
+    }
 }

src/Parser/StatementFilter.php

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * This file is part of the Moodle Plugin CI package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * Copyright (c) 2024 Moodle Pty Ltd <[email protected]>
+ * License http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace MoodlePluginCI\PluginValidate\Finder;
+
+use PhpParser\Node\Name;
+
+/**
+ * Finds function call.
+ */
+class FunctionCallFinder extends AbstractParserFinder
+{
+    public function getType(): string
+    {
+        return 'function call';
+    }
+
+    public function findTokens($file, FileTokens $fileTokens): void
+    {
+        $statements = $this->parser->parseFile($file);
+
+        foreach ($this->filter->filterFunctionCalls($statements) as $funccall) {
+            if ($funccall->name instanceof Name) {
+                $fileTokens->compare((string) $funccall->name);
+            }
+        }
+    }
+}

src/PluginValidate/Finder/FileTokens.php

@@ -17,6 +17,7 @@
 use MoodlePluginCI\PluginValidate\Finder\ClassFinder;
 use MoodlePluginCI\PluginValidate\Finder\FileTokens;
 use MoodlePluginCI\PluginValidate\Finder\FinderInterface;
+use MoodlePluginCI\PluginValidate\Finder\FunctionCallFinder;
 use MoodlePluginCI\PluginValidate\Finder\FunctionFinder;
 use MoodlePluginCI\PluginValidate\Finder\LangFinder;
 use MoodlePluginCI\PluginValidate\Finder\TableFinder;
@@ -98,6 +99,9 @@ public function addMessagesFromTokens(string $type, FileTokens $fileTokens): voi
                 $this->addSuccess(sprintf('In %s, found %s %s', $fileTokens->file, $type, implode(' OR ', $token->tokens)));
             } else {
                 $this->addError(sprintf('In %s, failed to find %s %s', $fileTokens->file, $type, implode(' OR ', $token->tokens)));
+                if ($fileTokens->hasHint()) {
+                    $this->addError(sprintf('Hint: %s', $fileTokens->hint));
+                }
             }
         }
     }
@@ -115,6 +119,7 @@ public function verifyRequirements(): void
         $this->findRequiredTokens(new TableFinder(), [$this->requirements->getRequiredTables()]);
         $this->findRequiredTokens(new TablePrefixFinder(), [$this->requirements->getRequiredTablePrefix()]);
         $this->findRequiredTokens(new BehatTagFinder(), $this->requirements->getRequiredBehatTags());
+        $this->findRequiredTokens(new FunctionCallFinder(), $this->requirements->getRequiredFunctionCalls());
     }
 
     /**

src/PluginValidate/Finder/FunctionCallFinder.php

@@ -76,6 +76,13 @@ protected function fileExists(string $file): bool
         return file_exists($this->plugin->directory . '/' . $file);
     }
 
+    /**
+     * Required function calls.
+     *
+     * @return FileTokens[]
+     */
+    abstract public function getRequiredFunctionCalls(): array;
+
     /**
      * An array of required files, paths are relative to the plugin directory.
      *

src/PluginValidate/PluginValidate.php

@@ -50,4 +50,15 @@ public function getRequiredStrings(): FileTokens
     {
         return FileTokens::create($this->getLangFile())->mustHave('filtername');
     }
+
+    public function getRequiredFunctionCalls(): array
+    {
+        if ($this->moodleVersion <= 404 && !$this->fileExists('classes/text_filter.php')) {
+            return [];
+        }
+
+        return [
+            FileTokens::create('filter.php')->mustHave('class_alias')->notFoundHint('https://moodledev.io/docs/4.5/devupdate#filter-plugins'),
+        ];
+    }
 }

src/PluginValidate/Requirements/AbstractRequirements.php

@@ -46,6 +46,11 @@ public function getRequiredClasses(): array
         return [];
     }
 
+    public function getRequiredFunctionCalls(): array
+    {
+        return [];
+    }
+
     public function getRequiredStrings(): FileTokens
     {
         return FileTokens::create($this->getLangFile())->mustHave('pluginname');