New CodeCoverageIgnoreDeprecated sniff

Yoast/Sniffs/Commenting/CodeCoverageIgnoreDeprecatedSniff.php

@@ -0,0 +1,117 @@
+<?php
+/**
+ * YoastCS\Yoast\Sniffs\Commenting\CodeCoverageIgnoreDeprecatedSniff.
+ *
+ * @package Yoast\YoastCS
+ * @author  Juliette Reinders Folmer
+ * @license https://opensource.org/licenses/MIT MIT
+ */
+
+namespace YoastCS\Yoast\Sniffs\Commenting;
+
+use PHP_CodeSniffer\Sniffs\Sniff;
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Util\Tokens;
+
+/**
+ * Verifies functions which are marked as `@deprecated` have a `@codeCoverageIgnore` tag
+ * in their docblock.
+ *
+ * @package Yoast\YoastCS
+ * @author  Juliette Reinders Folmer
+ *
+ * @since   1.1.0
+ */
+class CodeCoverageIgnoreDeprecatedSniff implements Sniff {
+
+	/**
+	 * Returns an array of tokens this test wants to listen for.
+	 *
+	 * @return array
+	 */
+	public function register() {
+		return array(
+			T_FUNCTION,
+		);
+	}
+
+	/**
+	 * Processes this test, when one of its tokens is encountered.
+	 *
+	 * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
+	 * @param int                         $stackPtr  The position of the current
+	 *                                               in the stack passed in $tokens.
+	 *
+	 * @return void
+	 */
+	public function process( File $phpcsFile, $stackPtr ) {
+
+		$tokens = $phpcsFile->getTokens();
+		$find   = Tokens::$methodPrefixes;
+		$find[] = T_WHITESPACE;
+
+		$commentEnd = $stackPtr;
+		do {
+			$commentEnd = $phpcsFile->findPrevious( $find, ( $commentEnd - 1 ), null, true );
+		} while ( $tokens[ $commentEnd ]['line'] === $tokens[ $stackPtr ]['line'] );
+
+		if ( $tokens[ $commentEnd ]['code'] !== T_DOC_COMMENT_CLOSE_TAG
+			|| $tokens[ $commentEnd ]['line'] !== ( $tokens[ $stackPtr ]['line'] - 1 )
+		) {
+			// Function without (proper) docblock. Not our concern.
+			return;
+		}
+
+		$commentStart = $tokens[ $commentEnd ]['comment_opener'];
+
+		$deprecated = false;
+		foreach ( $tokens[ $commentStart ]['comment_tags'] as $tag ) {
+			if ( $tokens[ $tag ]['content'] === '@deprecated' ) {
+				$deprecated = true;
+				break;
+			}
+		}
+
+		if ( $deprecated === false ) {
+			// Not a deprecated function.
+			return;
+		}
+
+		$codeCoverageIgnore = false;
+		foreach ( $tokens[ $commentStart ]['comment_tags'] as $tag ) {
+			if ( $tokens[ $tag ]['content'] === '@codeCoverageIgnore' ) {
+				$codeCoverageIgnore = true;
+				break;
+			}
+		}
+
+		if ( $codeCoverageIgnore === true ) {
+			// Docblock contains the @codeCoverageIgnore tag.
+			return;
+		}
+
+		$hasTagAsString = $phpcsFile->findNext( T_DOC_COMMENT_STRING, ( $commentStart + 1 ), $commentEnd, false, 'codeCoverageIgnore' );
+		if ( $hasTagAsString !== false ) {
+			$prev = $phpcsFile->findPrevious( T_DOC_COMMENT_WHITESPACE, ( $hasTagAsString - 1 ), $commentStart, true );
+			if ( $prev !== false && $tokens[ $prev ]['code'] === T_DOC_COMMENT_STAR ) {
+				$fix = $phpcsFile->addFixableError(
+					'The `codeCoverageIgnore` annotation in the function docblock needs to be prefixed with an `@`.',
+					$hasTagAsString,
+					'NotTag'
+				);
+				if ( $fix === true ) {
+					$phpcsFile->fixer->addContentBefore( $hasTagAsString, '@' );
+				}
+
+				return;
+			}
+		}
+
+		// If we're still here, the tag is missing.
+		$phpcsFile->addError(
+			'The function is marked as deprecated, but the docblock does not contain a `@codeCoverageIgnore` annotation.',
+			$stackPtr,
+			'Missing'
+		);
+	}
+}

Yoast/Tests/Commenting/CodeCoverageIgnoreDeprecatedUnitTest.inc

@@ -0,0 +1,56 @@
+<?php
+
+class SomeThing {
+
+	/**
+	 * Active (non-deprecated) function.
+	 */
+	function activeFunction() {}
+
+	/**
+	 * @deprecated x.x
+	 * @codeCoverageIgnore
+	 */
+	public /* don't get confused by this */ function correctDocblock() {
+		// Code
+    } // end function
+
+    public function functionWithoutDocblock {}
+
+	/**
+	 * @codeCoverageIgnore
+	 * @deprecated x.x
+	 */
+	private static function correctDocblockReverseOrder() {}
+
+	/**
+	 * @deprecated x.x
+	 *
+	 * @param string $param1 Short desc.
+	 * @param string $param2 Short desc.
+	 *
+	 * @return bool
+	 *
+	 * @codeCoverageIgnore
+	 */
+	protected function correctDocblockOtherTagsIrrelevant() {}
+
+	/**
+	 * @deprecated x.x
+	 *
+	 * codeCoverageIgnore
+	 */
+	private static function ignoreNotAsTag() {}
+
+	/**
+	 * @deprecated x.x
+	 *
+	 * This is a sentence containing the phrase codeCoverageIgnore, but should not be regarded as the tag.
+	 */
+	static protected function missingCodeCoverageIgnore() {}
+
+	/**
+	 * @deprecated x.x
+	 */
+	public function missingCodeCoverageIgnore() {}
+}

Yoast/Tests/Commenting/CodeCoverageIgnoreDeprecatedUnitTest.inc.fixed

@@ -0,0 +1,56 @@
+<?php
+
+class SomeThing {
+
+	/**
+	 * Active (non-deprecated) function.
+	 */
+	function activeFunction() {}
+
+	/**
+	 * @deprecated x.x
+	 * @codeCoverageIgnore
+	 */
+	public /* don't get confused by this */ function correctDocblock() {
+		// Code
+    } // end function
+
+    public function functionWithoutDocblock {}
+
+	/**
+	 * @codeCoverageIgnore
+	 * @deprecated x.x
+	 */
+	private static function correctDocblockReverseOrder() {}
+
+	/**
+	 * @deprecated x.x
+	 *
+	 * @param string $param1 Short desc.
+	 * @param string $param2 Short desc.
+	 *
+	 * @return bool
+	 *
+	 * @codeCoverageIgnore
+	 */
+	protected function correctDocblockOtherTagsIrrelevant() {}
+
+	/**
+	 * @deprecated x.x
+	 *
+	 * @codeCoverageIgnore
+	 */
+	private static function ignoreNotAsTag() {}
+
+	/**
+	 * @deprecated x.x
+	 *
+	 * This is a sentence containing the phrase codeCoverageIgnore, but should not be regarded as the tag.
+	 */
+	static protected function missingCodeCoverageIgnore() {}
+
+	/**
+	 * @deprecated x.x
+	 */
+	public function missingCodeCoverageIgnore() {}
+}

Yoast/Tests/Commenting/CodeCoverageIgnoreDeprecatedUnitTest.php

@@ -0,0 +1,43 @@
+<?php
+/**
+ * Unit test class for the Yoast Coding Standard.
+ *
+ * @package Yoast\YoastCS
+ * @license https://opensource.org/licenses/MIT MIT
+ */
+
+namespace YoastCS\Yoast\Tests\Commenting;
+
+use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
+
+/**
+ * Unit test class for the CodeCoverageIgnoreDeprecated sniff.
+ *
+ * @package Yoast\YoastCS
+ *
+ * @since   1.1.0
+ */
+class CodeCoverageIgnoreDeprecatedUnitTest extends AbstractSniffUnitTest {
+
+	/**
+	 * Returns the lines where errors should occur.
+	 *
+	 * @return array <int line number> => <int number of errors>
+	 */
+	public function getErrorList() {
+		return array(
+			41 => 1,
+			50 => 1,
+			55 => 1,
+		);
+	}
+
+	/**
+	 * Returns the lines where warnings should occur.
+	 *
+	 * @return array <int line number> => <int number of warnings>
+	 */
+	public function getWarningList() {
+		return array();
+	}
+}