maintenance/findDeprecated.php

   1 <?php
   2 /**
   3  * Maintenance script that recursively scans MediaWiki's PHP source tree
   4  * for deprecated functions and methods and pretty-prints the results.
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License along
  17  * with this program; if not, write to the Free Software Foundation, Inc.,
  18  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  19  * http://www.gnu.org/copyleft/gpl.html
  20  *
  21  * @file
  22  * @ingroup Maintenance
  23  * @phan-file-suppress PhanUndeclaredProperty Lots of custom properties
  24  */
  25
  26 // @codeCoverageIgnoreStart
  27 require_once __DIR__ . '/Maintenance.php';
  28 require_once __DIR__ . '/../vendor/autoload.php';
  29 // @codeCoverageIgnoreEnd
  30
  31 /**
  32  * A PHPParser node visitor that associates each node with its file name.
  33  */
  34 class FileAwareNodeVisitor extends PhpParser\NodeVisitorAbstract {
  35         private $currentFile = null;
  36
  37         public function enterNode( PhpParser\Node $node ) {
  38                 $retVal = parent::enterNode( $node );
  39                 $node->filename = $this->currentFile;
  40                 return $retVal;
  41         }
  42
  43         public function setCurrentFile( $filename ) {
  44                 $this->currentFile = $filename;
  45         }
  46
  47         public function getCurrentFile() {
  48                 return $this->currentFile;
  49         }
  50 }
  51
  52 /**
  53  * A PHPParser node visitor that finds deprecated functions and methods.
  54  */
  55 class DeprecatedInterfaceFinder extends FileAwareNodeVisitor {
  56
  57         private $currentClass = null;
  58
  59         private $foundNodes = [];
  60
  61         public function getFoundNodes() {
  62                 // Sort results by version, then by filename, then by name.
  63                 foreach ( $this->foundNodes as &$nodes ) {
  64                         uasort( $nodes, static function ( $a, $b ) {
  65                                 return ( $a['filename'] . $a['name'] ) <=> ( $b['filename'] . $b['name'] );
  66                         } );
  67                 }
  68                 ksort( $this->foundNodes );
  69                 return $this->foundNodes;
  70         }
  71
  72         /**
  73          * Check whether a function or method includes a call to wfDeprecated(),
  74          * indicating that it is a hard-deprecated interface.
  75          * @param PhpParser\Node $node
  76          * @return bool
  77          */
  78         public function isHardDeprecated( PhpParser\Node $node ) {
  79                 if ( !$node->stmts ) {
  80                         return false;
  81                 }
  82                 foreach ( $node->stmts as $stmt ) {
  83                         if (
  84                                 $stmt instanceof PhpParser\Node\Expr\FuncCall
  85                                 && $stmt->name->toString() === 'wfDeprecated'
  86                         ) {
  87                                 return true;
  88                         }
  89                         return false;
  90                 }
  91         }
  92
  93         public function enterNode( PhpParser\Node $node ) {
  94                 $retVal = parent::enterNode( $node );
  95
  96                 if ( $node instanceof PhpParser\Node\Stmt\ClassLike ) {
  97                         $this->currentClass = $node->name;
  98                 }
  99
 100                 if ( $node instanceof PhpParser\Node\FunctionLike ) {
 101                         $docComment = $node->getDocComment();
 102                         if ( !$docComment ) {
 103                                 return;
 104                         }
 105                         if ( !preg_match( '/@deprecated.*(\d+\.\d+)/', $docComment->getText(), $matches ) ) {
 106                                 return;
 107                         }
 108                         $version = $matches[1];
 109
 110                         if ( $node instanceof PhpParser\Node\Stmt\ClassMethod ) {
 111                                 $name = $this->currentClass . '::' . $node->name;
 112                         } else {
 113                                 $name = $node->name;
 114                         }
 115
 116                         $this->foundNodes[ $version ][] = [
 117                                 'filename' => $node->filename,
 118                                 'line'     => $node->getLine(),
 119                                 'name'     => $name,
 120                                 'hard'     => $this->isHardDeprecated( $node ),
 121                         ];
 122                 }
 123
 124                 return $retVal;
 125         }
 126 }
 127
 128 /**
 129  * Maintenance task that recursively scans MediaWiki PHP files for deprecated
 130  * functions and interfaces and produces a report.
 131  */
 132 class FindDeprecated extends Maintenance {
 133         public function __construct() {
 134                 parent::__construct();
 135                 $this->addDescription( 'Find deprecated interfaces' );
 136         }
 137
 138         /**
 139          * @return SplFileInfo[]
 140          */
 141         public function getFiles() {
 142                 global $IP;
 143
 144                 $files = new RecursiveDirectoryIterator( $IP . '/includes' );
 145                 $files = new RecursiveIteratorIterator( $files );
 146                 $files = new RegexIterator( $files, '/\.php$/' );
 147                 return iterator_to_array( $files, false );
 148         }
 149
 150         public function execute() {
 151                 global $IP;
 152
 153                 $files = $this->getFiles();
 154                 $chunkSize = (int)ceil( count( $files ) / 72 );
 155
 156                 $parser = ( new PhpParser\ParserFactory )->create( PhpParser\ParserFactory::PREFER_PHP7 );
 157                 $traverser = new PhpParser\NodeTraverser;
 158                 $finder = new DeprecatedInterfaceFinder;
 159                 $traverser->addVisitor( $finder );
 160
 161                 $fileCount = count( $files );
 162
 163                 for ( $i = 0; $i < $fileCount; $i++ ) {
 164                         $file = $files[$i];
 165                         $code = file_get_contents( $file );
 166
 167                         if ( !str_contains( $code, '@deprecated' ) ) {
 168                                 continue;
 169                         }
 170
 171                         $finder->setCurrentFile( substr( $file->getPathname(), strlen( $IP ) + 1 ) );
 172                         $nodes = $parser->parse( $code );
 173                         $traverser->traverse( $nodes );
 174
 175                         if ( $i % $chunkSize === 0 ) {
 176                                 $percentDone = 100 * $i / $fileCount;
 177                                 fprintf( STDERR, "\r[%-72s] %d%%", str_repeat( '#', $i / $chunkSize ), $percentDone );
 178                         }
 179                 }
 180
 181                 fprintf( STDERR, "\r[%'#-72s] 100%%\n", '' );
 182
 183                 // Colorize output if STDOUT is an interactive terminal.
 184                 if ( posix_isatty( STDOUT ) ) {
 185                         $versionFmt = "\n* Deprecated since \033[37;1m%s\033[0m:\n";
 186                         $entryFmt = "  %s \033[33;1m%s\033[0m (%s:%d)\n";
 187                 } else {
 188                         $versionFmt = "\n* Deprecated since %s:\n";
 189                         $entryFmt = "  %s %s (%s:%d)\n";
 190                 }
 191
 192                 foreach ( $finder->getFoundNodes() as $version => $nodes ) {
 193                         printf( $versionFmt, $version );
 194                         foreach ( $nodes as $node ) {
 195                                 printf(
 196                                         $entryFmt,
 197                                         $node['hard'] ? '+' : '-',
 198                                         $node['name'],
 199                                         $node['filename'],
 200                                         $node['line']
 201                                 );
 202                         }
 203                 }
 204                 printf( "\nlegend:\n -: soft-deprecated\n +: hard-deprecated (via wfDeprecated())\n" );
 205         }
 206 }
 207
 208 // @codeCoverageIgnoreStart
 209 $maintClass = FindDeprecated::class;
 210 require_once RUN_MAINTENANCE_IF_MAIN;
 211 // @codeCoverageIgnoreEnd