Add a maintenance script for finding deprecated interfaces

Add a maintenance script, findDeprecated.php, which iterates through
$IP/include/**.php, looking for functions and methods which have been marked as
deprecated (via a '@deprecated' tag in the doc-block), and then prints a
detailed report indicating the version, file, line and version of each
deprecated interface.

Change-Id: I9518a52b8c51ee972552a94f5367c1faa7e04a3a

diff --git a/composer.json b/composer.json
index b4878c9..9775823 100644 (file)
--- a/composer.json
+++ b/composer.json
@@ -42,6 +42,7 @@
                "justinrainbow/json-schema": "~1.3",
                "mediawiki/mediawiki-codesniffer": "0.4.0",
                "monolog/monolog": "~1.17.2",
+               "nikic/php-parser": "1.4.1",
                "nmred/kafka-php": "0.1.4",
                "phpunit/phpunit": "3.7.37",
                "wikimedia/avro": "1.7.7"

diff --git a/maintenance/findDeprecated.php b/maintenance/findDeprecated.php
new file mode 100644 (file)
index 0000000..cbb1d5b
--- /dev/null
+++ b/maintenance/findDeprecated.php
@@ -0,0 +1,199 @@
+<?php
+/**
+ * Maintenance script that recursively scans MediaWiki's PHP source tree
+ * for deprecated functions and methods and pretty-prints the results.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * http://www.gnu.org/copyleft/gpl.html
+ *
+ * @file
+ * @ingroup Maintenance
+ */
+
+require_once __DIR__ . '/Maintenance.php';
+require_once __DIR__ . '/../vendor/autoload.php';
+
+/**
+ * A PHPParser node visitor that associates each node with its file name.
+ */
+class FileAwareNodeVisitor extends PhpParser\NodeVisitorAbstract {
+       private $currentFile = null;
+
+       public function enterNode( PhpParser\Node $node ) {
+               $retVal = parent::enterNode( $node );
+               $node->filename = $this->currentFile;
+               return $retVal;
+       }
+
+       public function setCurrentFile( $filename ) {
+               $this->currentFile = $filename;
+       }
+
+       public function getCurrentFile() {
+               return $this->currentFile;
+       }
+}
+
+/**
+ * A PHPParser node visitor that finds deprecated functions and methods.
+ */
+class DeprecatedInterfaceFinder extends FileAwareNodeVisitor {
+
+       private $currentClass = null;
+
+       private $foundNodes = array();
+
+       public function getFoundNodes() {
+               // Sort results by version, then by filename, then by name.
+               foreach ( $this->foundNodes as $version => &$nodes ) {
+                       uasort( $nodes, function ( $a, $b ) {
+                               return ( $a['filename'] . $a['name'] ) < ( $b['filename'] . $b['name'] ) ? -1 : 1;
+                       } );
+               }
+               ksort( $this->foundNodes );
+               return $this->foundNodes;
+       }
+
+       /**
+        * Check whether a function or method includes a call to wfDeprecated(),
+        * indicating that it is a hard-deprecated interface.
+        */
+       public function isHardDeprecated( PhpParser\Node $node ) {
+               foreach ( $node->stmts as $stmt ) {
+                       if (
+                               $stmt instanceof PhpParser\Node\Expr\FuncCall
+                               && $stmt->name->toString() === 'wfDeprecated'
+                       ) {
+                               return true;
+                       }
+                       return false;
+               }
+       }
+
+       public function enterNode( PhpParser\Node $node ) {
+               $retVal = parent::enterNode( $node );
+
+               if ( $node instanceof PhpParser\Node\Stmt\ClassLike ) {
+                       $this->currentClass = $node->name;
+               }
+
+               if ( $node instanceof PhpParser\Node\FunctionLike ) {
+                       $docComment = $node->getDocComment();
+                       if ( !$docComment ) {
+                               return;
+                       }
+                       if ( !preg_match( '/@deprecated.*(\d+\.\d+)/', $docComment->getText(), $matches ) ) {
+                               return;
+                       }
+                       $version = $matches[1];
+
+                       if ( $node instanceof PhpParser\Node\Stmt\ClassMethod ) {
+                               $name = $this->currentClass . '::' . $node->name;
+                       } else {
+                               $name = $node->name;
+                       }
+
+                       $this->foundNodes[ $version ][] = array(
+                               'filename' => $node->filename,
+                               'line'     => $node->getLine(),
+                               'name'     => $name,
+                               'hard'     => $this->isHardDeprecated( $node ),
+                       );
+               }
+
+               return $retVal;
+       }
+}
+
+
+/**
+ * Maintenance task that recursively scans MediaWiki PHP files for deprecated
+ * functions and interfaces and produces a report.
+ */
+class FindDeprecated extends Maintenance {
+       public function __construct() {
+               parent::__construct();
+               $this->mDescription = 'Find deprecated interfaces';
+       }
+
+       public function getFiles() {
+               global $IP;
+
+               $files = new RecursiveDirectoryIterator( $IP . '/includes' );
+               $files = new RecursiveIteratorIterator( $files );
+               $files = new RegexIterator( $files, '/\.php$/' );
+               return iterator_to_array( $files, false );
+       }
+
+       public function execute() {
+               global $IP;
+
+               $files = $this->getFiles();
+               $chunkSize = ceil( count( $files ) / 72 );
+
+               $parser = new PhpParser\Parser( new PhpParser\Lexer\Emulative );
+               $traverser = new PhpParser\NodeTraverser;
+               $finder = new DeprecatedInterfaceFinder;
+               $traverser->addVisitor( $finder );
+
+               $fileCount = count( $files );
+
+               for ( $i = 0; $i < $fileCount; $i++ ) {
+                       $file = $files[$i];
+                       $code = file_get_contents( $file );
+
+                       if ( strpos( $code, '@deprecated' ) === -1 ) {
+                               continue;
+                       }
+
+                       $finder->setCurrentFile( substr( $file->getPathname(), strlen( $IP ) + 1 ) );
+                       $nodes = $parser->parse( $code, array( 'throwOnError' => false ) );
+                       $traverser->traverse( $nodes );
+
+                       if ( $i % $chunkSize === 0 ) {
+                               $percentDone = 100 * $i / $fileCount;
+                               fprintf( STDERR, "\r[%-72s] %d%%", str_repeat( '#', $i / $chunkSize ), $percentDone );
+                       }
+               }
+
+               fprintf( STDERR, "\r[%'#-72s] 100%%\n", '' );
+
+               // Colorize output if STDOUT is an interactive terminal.
+               if ( posix_isatty( STDOUT ) ) {
+                       $versionFmt = "\n* Deprecated since \033[37;1m%s\033[0m:\n";
+                       $entryFmt = "  %s \033[33;1m%s\033[0m (%s:%d)\n";
+               } else {
+                       $versionFmt = "\n* Deprecated since %s:\n";
+                       $entryFmt = "  %s %s (%s:%d)\n";
+               }
+
+               foreach ( $finder->getFoundNodes() as $version => $nodes ) {
+                       printf( $versionFmt, $version );
+                       foreach ( $nodes as $node ) {
+                               printf(
+                                       $entryFmt,
+                                       $node['hard'] ? '+' : '-',
+                                       $node['name'],
+                                       $node['filename'],
+                                       $node['line']
+                               );
+                       }
+               }
+               printf( "\nlegend:\n -: soft-deprecated\n +: hard-deprecated (via wfDeprecated())\n" );
+       }
+}
+
+$maintClass = 'FindDeprecated';
+require_once RUN_MAINTENANCE_IF_MAIN;