maintenance/findHooks.php

   1 <?php
   2 /**
   3  * Simple script that try to find documented hook and hooks actually
   4  * in the code and show what's missing.
   5  *
   6  * This script assumes that:
   7  * - hooks names in hooks.txt are at the beginning of a line and single quoted.
   8  * - hooks names in code are the first parameter of Hooks::run.
   9  *
  10  * if --online option is passed, the script will compare the hooks in the code
  11  * with the ones at https://www.mediawiki.org/wiki/Manual:Hooks
  12  *
  13  * Any instance of Hooks::run that doesn't meet these requirements will be noted.
  14  *
  15  * Copyright © Antoine Musso
  16  *
  17  * This program is free software; you can redistribute it and/or modify
  18  * it under the terms of the GNU General Public License as published by
  19  * the Free Software Foundation; either version 2 of the License, or
  20  * (at your option) any later version.
  21  *
  22  * This program is distributed in the hope that it will be useful,
  23  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  24  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  25  * GNU General Public License for more details.
  26  *
  27  * You should have received a copy of the GNU General Public License along
  28  * with this program; if not, write to the Free Software Foundation, Inc.,
  29  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  30  * http://www.gnu.org/copyleft/gpl.html
  31  *
  32  * @file
  33  * @ingroup Maintenance
  34  * @author Antoine Musso <hashar at free dot fr>
  35  */
  36
  37 use MediaWiki\MediaWikiServices;
  38
  39 require_once __DIR__ . '/Maintenance.php';
  40
  41 /**
  42  * Maintenance script that compares documented and actually present mismatches.
  43  *
  44  * @ingroup Maintenance
  45  */
  46 class FindHooks extends Maintenance {
  47         const FIND_NON_RECURSIVE = 0;
  48         const FIND_RECURSIVE = 1;
  49
  50         /*
  51          * Hooks that are ignored
  52          */
  53         protected static $ignore = [ 'Test' ];
  54
  55         public function __construct() {
  56                 parent::__construct();
  57                 $this->addDescription( 'Find hooks that are undocumented, missing, or just plain wrong' );
  58                 $this->addOption( 'online', 'Check against MediaWiki.org hook documentation' );
  59         }
  60
  61         public function getDbType() {
  62                 return Maintenance::DB_NONE;
  63         }
  64
  65         public function execute() {
  66                 global $IP;
  67
  68                 $documentedHooks = $this->getHooksFromDoc( $IP . '/docs/hooks.txt' );
  69                 $potentialHooks = [];
  70                 $badHooks = [];
  71
  72                 $recurseDirs = [
  73                         "$IP/includes/",
  74                         "$IP/mw-config/",
  75                         "$IP/languages/",
  76                         "$IP/maintenance/",
  77                         // Omit $IP/tests/phpunit as it contains hook tests that shouldn't be documented
  78                         "$IP/tests/parser",
  79                         "$IP/tests/phpunit/suites",
  80                 ];
  81                 $nonRecurseDirs = [
  82                         "$IP/",
  83                 ];
  84                 $extraFiles = [
  85                         "$IP/tests/phpunit/MediaWikiTestCase.php",
  86                 ];
  87
  88                 foreach ( $recurseDirs as $dir ) {
  89                         $ret = $this->getHooksFromDir( $dir, self::FIND_RECURSIVE );
  90                         $potentialHooks = array_merge( $potentialHooks, $ret['good'] );
  91                         $badHooks = array_merge( $badHooks, $ret['bad'] );
  92                 }
  93                 foreach ( $nonRecurseDirs as $dir ) {
  94                         $ret = $this->getHooksFromDir( $dir );
  95                         $potentialHooks = array_merge( $potentialHooks, $ret['good'] );
  96                         $badHooks = array_merge( $badHooks, $ret['bad'] );
  97                 }
  98                 foreach ( $extraFiles as $file ) {
  99                         $potentialHooks = array_merge( $potentialHooks, $this->getHooksFromFile( $file ) );
 100                         $badHooks = array_merge( $badHooks, $this->getBadHooksFromFile( $file ) );
 101                 }
 102
 103                 $documented = array_keys( $documentedHooks );
 104                 $potential = array_keys( $potentialHooks );
 105                 $potential = array_unique( $potential );
 106                 $badHooks = array_diff( array_unique( $badHooks ), self::$ignore );
 107                 $todo = array_diff( $potential, $documented, self::$ignore );
 108                 $deprecated = array_diff( $documented, $potential, self::$ignore );
 109
 110                 // Check parameter count and references
 111                 $badParameterCount = $badParameterReference = [];
 112                 foreach ( $potentialHooks as $hook => $args ) {
 113                         if ( !isset( $documentedHooks[$hook] ) ) {
 114                                 // Not documented, but that will also be in $todo
 115                                 continue;
 116                         }
 117                         $argsDoc = $documentedHooks[$hook];
 118                         if ( $args === 'unknown' || $argsDoc === 'unknown' ) {
 119                                 // Could not get parameter information
 120                                 continue;
 121                         }
 122                         if ( count( $argsDoc ) !== count( $args ) ) {
 123                                 $badParameterCount[] = $hook . ': Doc: ' . count( $argsDoc ) . ' vs. Code: ' . count( $args );
 124                         } else {
 125                                 // Check if & is equal
 126                                 foreach ( $argsDoc as $index => $argDoc ) {
 127                                         $arg = $args[$index];
 128                                         if ( ( $arg[0] === '&' ) !== ( $argDoc[0] === '&' ) ) {
 129                                                 $badParameterReference[] = $hook . ': References different: Doc: ' . $argDoc .
 130                                                         ' vs. Code: ' . $arg;
 131                                         }
 132                                 }
 133                         }
 134                 }
 135
 136                 // Print the results
 137                 $this->printArray( 'Undocumented', $todo );
 138                 $this->printArray( 'Documented and not found', $deprecated );
 139                 $this->printArray( 'Unclear hook calls', $badHooks );
 140                 $this->printArray( 'Different parameter count', $badParameterCount );
 141                 $this->printArray( 'Different parameter reference', $badParameterReference );
 142
 143                 if ( !$todo && !$deprecated && !$badHooks
 144                         && !$badParameterCount && !$badParameterReference
 145                 ) {
 146                         $this->output( "Looks good!\n" );
 147                 } else {
 148                         $this->fatalError( 'The script finished with errors.' );
 149                 }
 150         }
 151
 152         /**
 153          * Get the hook documentation, either locally or from MediaWiki.org
 154          * @param string $doc
 155          * @return array Array: key => hook name; value => array of arguments or string 'unknown'
 156          */
 157         private function getHooksFromDoc( $doc ) {
 158                 if ( $this->hasOption( 'online' ) ) {
 159                         return $this->getHooksFromOnlineDoc();
 160                 } else {
 161                         return $this->getHooksFromLocalDoc( $doc );
 162                 }
 163         }
 164
 165         /**
 166          * Get hooks from a local file (for example docs/hooks.txt)
 167          * @param string $doc Filename to look in
 168          * @return array Array: key => hook name; value => array of arguments or string 'unknown'
 169          */
 170         private function getHooksFromLocalDoc( $doc ) {
 171                 $m = [];
 172                 $content = file_get_contents( $doc );
 173                 preg_match_all(
 174                         "/\n'(.*?)':.*((?:\n.+)*)/",
 175                         $content,
 176                         $m,
 177                         PREG_SET_ORDER
 178                 );
 179
 180                 // Extract the documented parameter
 181                 $hooks = [];
 182                 foreach ( $m as $match ) {
 183                         $args = [];
 184                         if ( isset( $match[2] ) ) {
 185                                 $n = [];
 186                                 if ( preg_match_all( "/\n(&?\\$\w+):.+/", $match[2], $n ) ) {
 187                                         $args = $n[1];
 188                                 }
 189                         }
 190                         $hooks[$match[1]] = $args;
 191                 }
 192                 return $hooks;
 193         }
 194
 195         /**
 196          * Get hooks from www.mediawiki.org using the API
 197          * @return array Array: key => hook name; value => string 'unknown'
 198          */
 199         private function getHooksFromOnlineDoc() {
 200                 $allhooks = $this->getHooksFromOnlineDocCategory( 'MediaWiki_hooks' );
 201                 $removed = $this->getHooksFromOnlineDocCategory( 'Removed_hooks' );
 202                 return array_diff_key( $allhooks, $removed );
 203         }
 204
 205         /**
 206          * @param string $title
 207          * @return array
 208          */
 209         private function getHooksFromOnlineDocCategory( $title ) {
 210                 $params = [
 211                         'action' => 'query',
 212                         'list' => 'categorymembers',
 213                         'cmtitle' => "Category:$title",
 214                         'cmlimit' => 500,
 215                         'format' => 'json',
 216                         'continue' => '',
 217                 ];
 218
 219                 $retval = [];
 220                 while ( true ) {
 221                         $json = MediaWikiServices::getInstance()->getHttpRequestFactory()->get(
 222                                 wfAppendQuery( 'https://www.mediawiki.org/w/api.php', $params ),
 223                                 [],
 224                                 __METHOD__
 225                         );
 226                         $data = FormatJson::decode( $json, true );
 227                         foreach ( $data['query']['categorymembers'] as $page ) {
 228                                 if ( preg_match( '/Manual\:Hooks\/([a-zA-Z0-9- :]+)/', $page['title'], $m ) ) {
 229                                         // parameters are unknown, because that needs parsing of wikitext
 230                                         $retval[str_replace( ' ', '_', $m[1] )] = 'unknown';
 231                                 }
 232                         }
 233                         if ( !isset( $data['continue'] ) ) {
 234                                 return $retval;
 235                         }
 236                         $params = array_replace( $params, $data['continue'] );
 237                 }
 238         }
 239
 240         /**
 241          * Get hooks from a PHP file
 242          * @param string $filePath Full file path to the PHP file.
 243          * @return array Array: key => hook name; value => array of arguments or string 'unknown'
 244          */
 245         private function getHooksFromFile( $filePath ) {
 246                 $content = file_get_contents( $filePath );
 247                 $m = [];
 248                 preg_match_all(
 249                         // All functions which runs hooks
 250                         '/(?:Hooks\:\:run|Hooks\:\:runWithoutAbort)\s*\(\s*' .
 251                                 // First argument is the hook name as string
 252                                 '([\'"])(.*?)\1' .
 253                                 // Comma for second argument
 254                                 '(?:\s*(,))?' .
 255                                 // Second argument must start with array to be processed
 256                                 '(?:\s*(?:array\s*\(|\[)' .
 257                                 // Matching inside array - allows one deep of brackets
 258                                 '((?:[^\(\)\[\]]|\((?-1)\)|\[(?-1)\])*)' .
 259                                 // End
 260                                 '[\)\]])?/',
 261                         $content,
 262                         $m,
 263                         PREG_SET_ORDER
 264                 );
 265
 266                 // Extract parameter
 267                 $hooks = [];
 268                 foreach ( $m as $match ) {
 269                         $args = [];
 270                         if ( isset( $match[4] ) ) {
 271                                 $n = [];
 272                                 if ( preg_match_all( '/((?:[^,\(\)]|\([^\(\)]*\))+)/', $match[4], $n ) ) {
 273                                         $args = array_map( 'trim', $n[1] );
 274                                         // remove empty entries from trailing spaces
 275                                         $args = array_filter( $args );
 276                                 }
 277                         } elseif ( isset( $match[3] ) ) {
 278                                 // Found a parameter for Hooks::run,
 279                                 // but could not extract the hooks argument,
 280                                 // because there are given by a variable
 281                                 $args = 'unknown';
 282                         }
 283                         $hooks[$match[2]] = $args;
 284                 }
 285
 286                 return $hooks;
 287         }
 288
 289         /**
 290          * Get bad hooks (where the hook name could not be determined) from a PHP file
 291          * @param string $filePath Full filename to the PHP file.
 292          * @return array Array of source code lines
 293          */
 294         private function getBadHooksFromFile( $filePath ) {
 295                 $content = file_get_contents( $filePath );
 296                 $m = [];
 297                 preg_match_all( '/(?:Hooks\:\:run|Hooks\:\:runWithoutAbort)\(\s*[^\s\'"].*/', $content, $m );
 298                 $list = [];
 299                 foreach ( $m[0] as $match ) {
 300                         $list[] = $match . "(" . $filePath . ")";
 301                 }
 302
 303                 return $list;
 304         }
 305
 306         /**
 307          * Get hooks from a directory of PHP files.
 308          * @param string $dir Directory path to start at
 309          * @param int $recurse Pass self::FIND_RECURSIVE
 310          * @return array Array: key => hook name; value => array of arguments or string 'unknown'
 311          */
 312         private function getHooksFromDir( $dir, $recurse = 0 ) {
 313                 $good = [];
 314                 $bad = [];
 315
 316                 if ( $recurse === self::FIND_RECURSIVE ) {
 317                         $iterator = new RecursiveIteratorIterator(
 318                                 new RecursiveDirectoryIterator( $dir, RecursiveDirectoryIterator::SKIP_DOTS ),
 319                                 RecursiveIteratorIterator::SELF_FIRST
 320                         );
 321                 } else {
 322                         $iterator = new DirectoryIterator( $dir );
 323                 }
 324
 325                 /** @var SplFileInfo $info */
 326                 foreach ( $iterator as $info ) {
 327                         // Ignore directories, work only on php files,
 328                         if ( $info->isFile() && in_array( $info->getExtension(), [ 'php', 'inc' ] )
 329                                 // Skip this file as it contains text that looks like a bad wfRunHooks() call
 330                                 && $info->getRealPath() !== __FILE__
 331                         ) {
 332                                 $good = array_merge( $good, $this->getHooksFromFile( $info->getRealPath() ) );
 333                                 $bad = array_merge( $bad, $this->getBadHooksFromFile( $info->getRealPath() ) );
 334                         }
 335                 }
 336
 337                 return [ 'good' => $good, 'bad' => $bad ];
 338         }
 339
 340         /**
 341          * Nicely sort an print an array
 342          * @param string $msg A message to show before the value
 343          * @param array $arr
 344          */
 345         private function printArray( $msg, $arr ) {
 346                 asort( $arr );
 347
 348                 foreach ( $arr as $v ) {
 349                         $this->output( "$msg: $v\n" );
 350                 }
 351         }
 352 }
 353
 354 $maintClass = FindHooks::class;
 355 require_once RUN_MAINTENANCE_IF_MAIN;