ValidationRunner.php

Go to the documentation of this file.

<?php
namespace MediaWiki\Extension\Translate\Validation;
 
use Exception;
use InvalidArgumentException;
use MediaWiki\Extension\Translate\MessageLoading\Message;
use MediaWiki\Extension\Translate\Services;
use MediaWiki\Extension\Translate\TranslatorInterface\Insertable\InsertablesSuggester;
use MediaWiki\Extension\Translate\Utilities\PHPVariableLoader;
use MediaWiki\Json\FormatJson;
use RuntimeException;
 
class ValidationRunner {
    protected $validators = [];
    private static $ignorePatterns;
 
    public function __construct(
        private readonly string $groupId,
    ) {
        if ( self::$ignorePatterns === null ) {
            // TODO: Review if this logic belongs in this class.
            self::reloadIgnorePatterns();
        }
    }
 
    protected static function foldValue( string $value ): string {
        return str_replace( ' ', '_', strtolower( $value ) );
    }
 
    public function setValidators( array $validatorConfigs ): void {
        $this->validators = [];
        foreach ( $validatorConfigs as $config ) {
            $this->addValidator( $config );
        }
    }
 
    public function addValidator( array $validatorConfig ): void {
        $validatorId = $validatorConfig['id'] ?? null;
        $className = $validatorConfig['class'] ?? null;
 
        if ( $validatorId !== null ) {
            $validator = ValidatorFactory::get(
                $validatorId,
                $validatorConfig['params'] ?? null
            );
        } elseif ( $className !== null ) {
            $validator = ValidatorFactory::loadInstance(
                $className,
                $validatorConfig['params'] ?? null
            );
        } else {
            throw new InvalidArgumentException(
                'Validator configuration does not specify the \'class\' or \'id\'.'
            );
        }
 
        $isInsertable = $validatorConfig['insertable'] ?? false;
        if ( $isInsertable && !$validator instanceof InsertablesSuggester ) {
            $actualClassName = get_class( $validator );
            throw new InvalidArgumentException(
                "Insertable validator $actualClassName does not implement InsertablesSuggester interface."
            );
        }
 
        $this->validators[] = [
            'instance' => $validator,
            'insertable' => $isInsertable,
            'enforce' => $validatorConfig['enforce'] ?? false,
            'include' => $validatorConfig['keymatch'] ?? $validatorConfig['include'] ?? false,
            'exclude' => $validatorConfig['exclude'] ?? false
        ];
    }
 
    public function getValidators(): array {
        return array_column( $this->validators, 'instance' );
    }
 
    public function getInsertableValidators(): array {
        $insertableValidators = [];
        foreach ( $this->validators as $validator ) {
            if ( $validator['insertable'] === true ) {
                $insertableValidators[] = $validator['instance'];
            }
        }
 
        return $insertableValidators;
    }
 
    public function validateMessage(
        Message $message,
        string $code,
        bool $ignoreWarnings = false
    ): ValidationResult {
        $errors = new ValidationIssues();
        $warnings = new ValidationIssues();
 
        foreach ( $this->validators as $validator ) {
            $this->runValidation(
                $validator,
                $message,
                $code,
                $errors,
                $warnings,
                $ignoreWarnings
            );
        }
 
        $errors = $this->filterValidations( $message->key(), $errors, $code );
        $warnings = $this->filterValidations( $message->key(), $warnings, $code );
 
        return new ValidationResult( $errors, $warnings );
    }
 
    public function quickValidate(
        Message $message,
        string $code,
        bool $ignoreWarnings = false
    ): ValidationResult {
        $errors = new ValidationIssues();
        $warnings = new ValidationIssues();
 
        foreach ( $this->validators as $validator ) {
            $this->runValidation(
                $validator,
                $message,
                $code,
                $errors,
                $warnings,
                $ignoreWarnings
            );
 
            $errors = $this->filterValidations( $message->key(), $errors, $code );
            $warnings = $this->filterValidations( $message->key(), $warnings, $code );
 
            if ( $warnings->hasIssues() || $errors->hasIssues() ) {
                break;
            }
        }
 
        return new ValidationResult( $errors, $warnings );
    }
 
    public static function reloadIgnorePatterns(): void {
        $validationExclusionFile = Services::getInstance()->getConfigHelper()->getValidationExclusionFile();
 
        if ( $validationExclusionFile === false ) {
            self::$ignorePatterns = [];
            return;
        }
 
        $list = PHPVariableLoader::loadVariableFromPHPFile(
            $validationExclusionFile,
            'validationExclusionList'
        );
        $keys = [ 'group', 'check', 'subcheck', 'code', 'message' ];
 
        if ( $list && !is_array( $list ) ) {
            throw new InvalidArgumentException(
                "validationExclusionList defined in $validationExclusionFile must be an array"
            );
        }
 
        foreach ( $list as $key => $pattern ) {
            foreach ( $keys as $checkKey ) {
                if ( !isset( $pattern[$checkKey] ) ) {
                    $list[$key][$checkKey] = '#';
                } elseif ( is_array( $pattern[$checkKey] ) ) {
                    $list[$key][$checkKey] =
                        array_map(
                            [ self::class, 'foldValue' ],
                            $pattern[$checkKey]
                        );
                } else {
                    $list[$key][$checkKey] = self::foldValue( $pattern[$checkKey] );
                }
            }
        }
 
        self::$ignorePatterns = $list;
    }
 
    private function filterValidations(
        string $messageKey,
        ValidationIssues $issues,
        string $targetLanguage
    ): ValidationIssues {
        $filteredIssues = new ValidationIssues();
 
        foreach ( $issues as $issue ) {
            foreach ( self::$ignorePatterns as $pattern ) {
                if ( $this->shouldIgnore( $messageKey, $issue, $this->groupId, $targetLanguage, $pattern ) ) {
                    continue 2;
                }
            }
            $filteredIssues->add( $issue );
        }
 
        return $filteredIssues;
    }
 
    private function shouldIgnore(
        string $messageKey,
        ValidationIssue $issue,
        string $messageGroupId,
        string $targetLanguage,
        array $pattern
    ): bool {
        return $this->matchesIgnorePattern( $pattern['group'], $messageGroupId )
            && $this->matchesIgnorePattern( $pattern['check'], $issue->type() )
            && $this->matchesIgnorePattern( $pattern['subcheck'], $issue->subType() )
            && $this->matchesIgnorePattern( $pattern['message'], $messageKey )
            && $this->matchesIgnorePattern( $pattern['code'], $targetLanguage );
    }
 
    private function matchesIgnorePattern( $pattern, string $value ): bool {
        if ( $pattern === '#' ) {
            return true;
        } elseif ( is_array( $pattern ) ) {
            return in_array( strtolower( $value ), $pattern, true );
        } else {
            return strtolower( $value ) === $pattern;
        }
    }
 
    protected function doesKeyMatch( string $key, array $keyMatches ): bool {
        $normalizedKey = lcfirst( $key );
        foreach ( $keyMatches as $match ) {
            if ( is_string( $match ) ) {
                if ( lcfirst( $match ) === $normalizedKey ) {
                    return true;
                }
                continue;
            }
 
            // The value is neither a string nor an array, should never happen but still handle it.
            if ( !is_array( $match ) ) {
                throw new InvalidArgumentException(
                    "Invalid key matcher configuration passed. Expected type: array or string. " .
                    "Received: " . get_debug_type( $match ) . ". match value: " . FormatJson::encode( $match )
                );
            }
 
            $matcherType = $match['type'];
            $pattern = $match['pattern'];
 
            // If regex matches, or wildcard matches return true, else continue processing.
            if (
                ( $matcherType === 'regex' && preg_match( $pattern, $normalizedKey ) === 1 ) ||
                ( $matcherType === 'wildcard' && fnmatch( $pattern, $normalizedKey ) )
            ) {
                return true;
            }
        }
 
        return false;
    }
 
    private function runValidation(
        array $validatorData,
        Message $message,
        string $targetLanguage,
        ValidationIssues $errors,
        ValidationIssues $warnings,
        bool $ignoreWarnings
    ): void {
        // Check if key match has been specified, and then check if the key matches it.
        $validator = $validatorData['instance'];
 
        $definition = $message->definition();
 
        try {
            $includedKeys = $validatorData['include'];
            if ( $includedKeys !== false && !$this->doesKeyMatch( $message->key(), $includedKeys ) ) {
                return;
            }
 
            $excludedKeys = $validatorData['exclude'];
            if ( $excludedKeys !== false && $this->doesKeyMatch( $message->key(), $excludedKeys ) ) {
                return;
            }
 
            if ( $validatorData['enforce'] === true ) {
                $errors->merge( $validator->getIssues( $message, $targetLanguage ) );
            } elseif ( !$ignoreWarnings ) {
                $warnings->merge( $validator->getIssues( $message, $targetLanguage ) );
            }
            // else: caller does not want warnings, skip running the validator
        } catch ( Exception $e ) {
            throw new RuntimeException(
                'An error occurred while validating message: ' . $message->key() . '; group: ' .
                $this->groupId . "; validator: " . get_class( $validator ) . "\n. Exception: $e"
            );
        }
    }
}