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 wfRunHooks.
   9  *
  10  * if --online option is passed, the script will compare the hooks in the code
  11  * with the ones at http://www.mediawiki.org/wiki/Manual:Hooks
  12  *
  13  * Any instance of wfRunHooks that doesn't meet these parameters 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 require_once __DIR__ . '/Maintenance.php';
  38
  39 /**
  40  * Maintenance script that compares documented and actually present mismatches.
  41  *
  42  * @ingroup Maintenance
  43  */
  44 class FindHooks extends Maintenance {
  45         /*
  46          * Hooks that are ignored
  47          */
  48         protected static $ignore = [ 'testRunLegacyHooks' ];
  49
  50         public function __construct() {
  51                 parent::__construct();
  52                 $this->addDescription( 'Find hooks that are undocumented, missing, or just plain wrong' );
  53                 $this->addOption( 'online', 'Check against MediaWiki.org hook documentation' );
  54         }
  55
  56         public function getDbType() {
  57                 return Maintenance::DB_NONE;
  58         }
  59
  60         public function execute() {
  61                 global $IP;
  62
  63                 $documentedHooks = $this->getHooksFromDoc( $IP . '/docs/hooks.txt' );
  64                 $potentialHooks = [];
  65                 $bad = [];
  66
  67                 // TODO: Don't hardcode the list of directories
  68                 $pathinc = [
  69                         $IP . '/',
  70                         $IP . '/includes/',
  71                         $IP . '/includes/actions/',
  72                         $IP . '/includes/api/',
  73                         $IP . '/includes/cache/',
  74                         $IP . '/includes/changes/',
  75                         $IP . '/includes/changetags/',
  76                         $IP . '/includes/clientpool/',
  77                         $IP . '/includes/content/',
  78                         $IP . '/includes/context/',
  79                         $IP . '/includes/dao/',
  80                         $IP . '/includes/db/',
  81                         $IP . '/includes/debug/',
  82                         $IP . '/includes/deferred/',
  83                         $IP . '/includes/diff/',
  84                         $IP . '/includes/exception/',
  85                         $IP . '/includes/export/',
  86                         $IP . '/includes/externalstore/',
  87                         $IP . '/includes/filebackend/',
  88                         $IP . '/includes/filerepo/',
  89                         $IP . '/includes/filerepo/file/',
  90                         $IP . '/includes/gallery/',
  91                         $IP . '/includes/htmlform/',
  92                         $IP . '/includes/import/',
  93                         $IP . '/includes/installer/',
  94                         $IP . '/includes/interwiki/',
  95                         $IP . '/includes/jobqueue/',
  96                         $IP . '/includes/json/',
  97                         $IP . '/includes/logging/',
  98                         $IP . '/includes/mail/',
  99                         $IP . '/includes/media/',
 100                         $IP . '/includes/page/',
 101                         $IP . '/includes/parser/',
 102                         $IP . '/includes/password/',
 103                         $IP . '/includes/rcfeed/',
 104                         $IP . '/includes/resourceloader/',
 105                         $IP . '/includes/revisiondelete/',
 106                         $IP . '/includes/search/',
 107                         $IP . '/includes/session/',
 108                         $IP . '/includes/site/',
 109                         $IP . '/includes/skins/',
 110                         $IP . '/includes/specialpage/',
 111                         $IP . '/includes/specials/',
 112                         $IP . '/includes/upload/',
 113                         $IP . '/includes/user/',
 114                         $IP . '/includes/utils/',
 115                         $IP . '/languages/',
 116                         $IP . '/maintenance/',
 117                         $IP . '/maintenance/language/',
 118                         $IP . '/tests/',
 119                         $IP . '/tests/parser/',
 120                         $IP . '/tests/phpunit/suites/',
 121                 ];
 122
 123                 foreach ( $pathinc as $dir ) {
 124                         $potentialHooks = array_merge( $potentialHooks, $this->getHooksFromPath( $dir ) );
 125                         $bad = array_merge( $bad, $this->getBadHooksFromPath( $dir ) );
 126                 }
 127
 128                 $documented = array_keys( $documentedHooks );
 129                 $potential = array_keys( $potentialHooks );
 130                 $potential = array_unique( $potential );
 131                 $bad = array_diff( array_unique( $bad ), self::$ignore );
 132                 $todo = array_diff( $potential, $documented, self::$ignore );
 133                 $deprecated = array_diff( $documented, $potential, self::$ignore );
 134
 135                 // Check parameter count and references
 136                 $badParameterCount = $badParameterReference = [];
 137                 foreach ( $potentialHooks as $hook => $args ) {
 138                         if ( !isset( $documentedHooks[$hook] ) ) {
 139                                 // Not documented, but that will also be in $todo
 140                                 continue;
 141                         }
 142                         $argsDoc = $documentedHooks[$hook];
 143                         if ( $args === 'unknown' || $argsDoc === 'unknown' ) {
 144                                 // Could not get parameter information
 145                                 continue;
 146                         }
 147                         if ( count( $argsDoc ) !== count( $args ) ) {
 148                                 $badParameterCount[] = $hook . ': Doc: ' . count( $argsDoc ) . ' vs. Code: ' . count( $args );
 149                         } else {
 150                                 // Check if & is equal
 151                                 foreach ( $argsDoc as $index => $argDoc ) {
 152                                         $arg = $args[$index];
 153                                         if ( ( $arg[0] === '&' ) !== ( $argDoc[0] === '&' ) ) {
 154                                                 $badParameterReference[] = $hook . ': References different: Doc: ' . $argDoc .
 155                                                         ' vs. Code: ' . $arg;
 156                                         }
 157                                 }
 158                         }
 159                 }
 160
 161                 // let's show the results:
 162                 $this->printArray( 'Undocumented', $todo );
 163                 $this->printArray( 'Documented and not found', $deprecated );
 164                 $this->printArray( 'Unclear hook calls', $bad );
 165                 $this->printArray( 'Different parameter count', $badParameterCount );
 166                 $this->printArray( 'Different parameter reference', $badParameterReference );
 167
 168                 if ( count( $todo ) == 0 && count( $deprecated ) == 0 && count( $bad ) == 0
 169                         && count( $badParameterCount ) == 0 && count( $badParameterReference ) == 0
 170                 ) {
 171                         $this->output( "Looks good!\n" );
 172                 } else {
 173                         $this->error( 'The script finished with errors.', 1 );
 174                 }
 175         }
 176
 177         /**
 178          * Get the hook documentation, either locally or from MediaWiki.org
 179          * @param string $doc
 180          * @return array Array: key => hook name; value => array of arguments or string 'unknown'
 181          */
 182         private function getHooksFromDoc( $doc ) {
 183                 if ( $this->hasOption( 'online' ) ) {
 184                         return $this->getHooksFromOnlineDoc();
 185                 } else {
 186                         return $this->getHooksFromLocalDoc( $doc );
 187                 }
 188         }
 189
 190         /**
 191          * Get hooks from a local file (for example docs/hooks.txt)
 192          * @param string $doc Filename to look in
 193          * @return array Array: key => hook name; value => array of arguments or string 'unknown'
 194          */
 195         private function getHooksFromLocalDoc( $doc ) {
 196                 $m = [];
 197                 $content = file_get_contents( $doc );
 198                 preg_match_all(
 199                         "/\n'(.*?)':.*((?:\n.+)*)/",
 200                         $content,
 201                         $m,
 202                         PREG_SET_ORDER
 203                 );
 204
 205                 // Extract the documented parameter
 206                 $hooks = [];
 207                 foreach ( $m as $match ) {
 208                         $args = [];
 209                         if ( isset( $match[2] ) ) {
 210                                 $n = [];
 211                                 if ( preg_match_all( "/\n(&?\\$\w+):.+/", $match[2], $n ) ) {
 212                                         $args = $n[1];
 213                                 }
 214                         }
 215                         $hooks[$match[1]] = $args;
 216                 }
 217                 return $hooks;
 218         }
 219
 220         /**
 221          * Get hooks from www.mediawiki.org using the API
 222          * @return array Array: key => hook name; value => string 'unknown'
 223          */
 224         private function getHooksFromOnlineDoc() {
 225                 $allhooks = $this->getHooksFromOnlineDocCategory( 'MediaWiki_hooks' );
 226                 $removed = $this->getHooksFromOnlineDocCategory( 'Removed_hooks' );
 227                 return array_diff_key( $allhooks, $removed );
 228         }
 229
 230         /**
 231          * @param string $title
 232          * @return array
 233          */
 234         private function getHooksFromOnlineDocCategory( $title ) {
 235                 $params = [
 236                         'action' => 'query',
 237                         'list' => 'categorymembers',
 238                         'cmtitle' => "Category:$title",
 239                         'cmlimit' => 500,
 240                         'format' => 'json',
 241                         'continue' => '',
 242                 ];
 243
 244                 $retval = [];
 245                 while ( true ) {
 246                         $json = Http::get(
 247                                 wfAppendQuery( 'http://www.mediawiki.org/w/api.php', $params ),
 248                                 [],
 249                                 __METHOD__
 250                         );
 251                         $data = FormatJson::decode( $json, true );
 252                         foreach ( $data['query']['categorymembers'] as $page ) {
 253                                 if ( preg_match( '/Manual\:Hooks\/([a-zA-Z0-9- :]+)/', $page['title'], $m ) ) {
 254                                         // parameters are unknown, because that needs parsing of wikitext
 255                                         $retval[str_replace( ' ', '_', $m[1] )] = 'unknown';
 256                                 }
 257                         }
 258                         if ( !isset( $data['continue'] ) ) {
 259                                 return $retval;
 260                         }
 261                         $params = array_replace( $params, $data['continue'] );
 262                 }
 263         }
 264
 265         /**
 266          * Get hooks from a PHP file
 267          * @param string $file Full filename to the PHP file.
 268          * @return array Array: key => hook name; value => array of arguments or string 'unknown'
 269          */
 270         private function getHooksFromFile( $file ) {
 271                 $content = file_get_contents( $file );
 272                 $m = [];
 273                 preg_match_all(
 274                         // All functions which runs hooks
 275                         '/(?:wfRunHooks|Hooks\:\:run|ContentHandler\:\:runLegacyHooks)\s*\(\s*' .
 276                                 // First argument is the hook name as string
 277                                 '([\'"])(.*?)\1' .
 278                                 // Comma for second argument
 279                                 '(?:\s*(,))?' .
 280                                 // Second argument must start with array to be processed
 281                                 '(?:\s*array\s*\(' .
 282                                 // Matching inside array - allows one deep of brackets
 283                                 '((?:[^\(\)]|\([^\(\)]*\))*)' .
 284                                 // End
 285                                 '\))?/',
 286                         $content,
 287                         $m,
 288                         PREG_SET_ORDER
 289                 );
 290
 291                 // Extract parameter
 292                 $hooks = [];
 293                 foreach ( $m as $match ) {
 294                         $args = [];
 295                         if ( isset( $match[4] ) ) {
 296                                 $n = [];
 297                                 if ( preg_match_all( '/((?:[^,\(\)]|\([^\(\)]*\))+)/', $match[4], $n ) ) {
 298                                         $args = array_map( 'trim', $n[1] );
 299                                 }
 300                         } elseif ( isset( $match[3] ) ) {
 301                                 // Found a parameter for Hooks::run,
 302                                 // but could not extract the hooks argument,
 303                                 // because there are given by a variable
 304                                 $args = 'unknown';
 305                         }
 306                         $hooks[$match[2]] = $args;
 307                 }
 308
 309                 return $hooks;
 310         }
 311
 312         /**
 313          * Get hooks from the source code.
 314          * @param string $path Directory where the include files can be found
 315          * @return array Array: key => hook name; value => array of arguments or string 'unknown'
 316          */
 317         private function getHooksFromPath( $path ) {
 318                 $hooks = [];
 319                 $dh = opendir( $path );
 320                 if ( $dh ) {
 321                         while ( ( $file = readdir( $dh ) ) !== false ) {
 322                                 if ( filetype( $path . $file ) == 'file' ) {
 323                                         $hooks = array_merge( $hooks, $this->getHooksFromFile( $path . $file ) );
 324                                 }
 325                         }
 326                         closedir( $dh );
 327                 }
 328
 329                 return $hooks;
 330         }
 331
 332         /**
 333          * Get bad hooks (where the hook name could not be determined) from a PHP file
 334          * @param string $file Full filename to the PHP file.
 335          * @return array Array of bad wfRunHooks() lines
 336          */
 337         private function getBadHooksFromFile( $file ) {
 338                 $content = file_get_contents( $file );
 339                 $m = [];
 340                 # We want to skip the "function wfRunHooks()" one.  :)
 341                 preg_match_all( '/(?<!function )wfRunHooks\(\s*[^\s\'"].*/', $content, $m );
 342                 $list = [];
 343                 foreach ( $m[0] as $match ) {
 344                         $list[] = $match . "(" . $file . ")";
 345                 }
 346
 347                 return $list;
 348         }
 349
 350         /**
 351          * Get bad hooks from the source code.
 352          * @param string $path Directory where the include files can be found
 353          * @return array Array of bad wfRunHooks() lines
 354          */
 355         private function getBadHooksFromPath( $path ) {
 356                 $hooks = [];
 357                 $dh = opendir( $path );
 358                 if ( $dh ) {
 359                         while ( ( $file = readdir( $dh ) ) !== false ) {
 360                                 # We don't want to read this file as it contains bad calls to wfRunHooks()
 361                                 if ( filetype( $path . $file ) == 'file' && !$path . $file == __FILE__ ) {
 362                                         $hooks = array_merge( $hooks, $this->getBadHooksFromFile( $path . $file ) );
 363                                 }
 364                         }
 365                         closedir( $dh );
 366                 }
 367
 368                 return $hooks;
 369         }
 370
 371         /**
 372          * Nicely output the array
 373          * @param string $msg A message to show before the value
 374          * @param array $arr
 375          * @param bool $sort Whether to sort the array (Default: true)
 376          */
 377         private function printArray( $msg, $arr, $sort = true ) {
 378                 if ( $sort ) {
 379                         asort( $arr );
 380                 }
 381
 382                 foreach ( $arr as $v ) {
 383                         $this->output( "$msg: $v\n" );
 384                 }
 385         }
 386 }
 387
 388 $maintClass = 'FindHooks';
 389 require_once RUN_MAINTENANCE_IF_MAIN;