wikimedia / mediawiki

maintenance/findDeprecated.php

<?php

For compatibility and reusability of your code, PSR1 recommends that a file should introduce either new symbols (like classes, functions, etc.) or have side-effects (like outputting something, or including other files), but not both at the same time. The first symbol is defined on line 31 and the first side effect is on line 25.

/**
 * 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;

Accessing filename on the interface PhpParser\Node suggest that you code against a concrete implementation. How about adding an instanceof check?

		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 = [];

	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 ) {
		if ( !$node->stmts ) {

Accessing stmts on the interface PhpParser\Node suggest that you code against a concrete implementation. How about adding an instanceof check?

			return false;
		}
		foreach ( $node->stmts as $stmt ) {

Accessing stmts on the interface PhpParser\Node suggest that you code against a concrete implementation. How about adding an instanceof check?

			if (
				$stmt instanceof PhpParser\Node\Expr\FuncCall
				&& $stmt->name->toString() === 'wfDeprecated'

The method toString does only exist in PhpParser\Node\Name, but not in PhpParser\Node\Expr.

			) {
				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;

Accessing name on the interface PhpParser\Node\FunctionLike suggest that you code against a concrete implementation. How about adding an instanceof check?

			}

			$this->foundNodes[ $version ][] = [
				'filename' => $node->filename,

Accessing filename on the interface PhpParser\Node\FunctionLike suggest that you code against a concrete implementation. How about adding an instanceof check?

				'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->addDescription( '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\ParserFactory )->create( PhpParser\ParserFactory::PREFER_PHP7 );
		$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, [ 'throwOnError' => false ] );
			$traverser->traverse( $nodes );

It seems like $nodes defined by $parser->parse($code, array('throwOnError' => false)) on line 164 can also be of type null; however, PhpParser\NodeTraverser::traverse() does only seem to accept array<integer,object<PhpParser\Node>>, maybe add an additional type check?

			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;