Merge branch 'release/1.2.0'

CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 
 This projects adheres to [Semantic Versioning](https://semver.org/) and [Keep a CHANGELOG](https://keepachangelog.com/).
 
+### [1.2.0] - 2018-12-21
+
+#### Added
+* PHPCS: New `Yoast.Commenting.FileComment` sniff.
+    This sniff is a wrapper around the `FileComment` sniff used in WordPressCS and manages the slightly different requirements for file comments set for the Yoast organisation, in particular:
+	- If a file is namespaced, no file comment is needed (and having one is discouraged).
+* PHPCS: New `Yoast.Namespaces.NamespaceDeclaration` sniff.
+    This sniff forbids the use of:
+    - Namespace declarations without a namespace name, i.e. `namespace;` which in effect means "global namespace".
+    - Scoped namespace declarations.
+    - Multiple namespace declarations in one file.
+
 ### [1.1.0] - 2018-12-18
 
 #### Added
@@ -218,6 +230,7 @@ Initial public release as a stand-alone package.
 [PHP Mess Detector]: https://github.com/phpmd/phpmd/blob/master/CHANGELOG
 [DealerDirect Composer PHPCS plugin]: https://github.com/Dealerdirect/phpcodesniffer-composer-installer/releases
 
+[1.2.0]: https://github.com/Yoast/yoastcs/compare/1.1.0...1.2.0
 [1.1.0]: https://github.com/Yoast/yoastcs/compare/1.0.0...1.1.0
 [1.0.0]: https://github.com/Yoast/yoastcs/compare/0.5.0...1.0.0
 [0.5]: https://github.com/Yoast/yoastcs/compare/0.4.3...0.5

Yoast/Sniffs/Commenting/CodeCoverageIgnoreDeprecatedSniff.php

@@ -1,11 +1,4 @@
 <?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;
 

Yoast/Sniffs/Commenting/FileCommentSniff.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace YoastCS\Yoast\Sniffs\Commenting;
+
+use PHP_CodeSniffer\Standards\Squiz\Sniffs\Commenting\FileCommentSniff as Squiz_FileCommentSniff;
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Util\Tokens;
+
+/**
+ * Namespaced files do not need a file docblock in YoastCS.
+ *
+ * Note: Files without a namespace declaration do still need a file docblock.
+ * This includes files which have a non-named namespace declaration which
+ * falls back to the global namespace.
+ *
+ * {@internal At this moment - December 2018 -, the WordPress-Docs standard
+ * uses the PHPCS Squiz standard commenting sniffs. For that reason, this Yoast
+ * sniff extends the Squiz sniff as well.
+ * Once WPCS introduces a WordPress native FileComment sniff, this sniff should
+ * probably extend the WordPress native version instead.
+ * If/when that comes into play, the code in the sniff needs to be reviewed to
+ * see if it's still relevant to have this sniff and if so, if the sniff needs
+ * adjustments.}}
+ *
+ * @package Yoast\YoastCS
+ * @author  Juliette Reinders Folmer
+ *
+ * @since   1.2.0
+ */
+class FileCommentSniff extends Squiz_FileCommentSniff {
+
+	/**
+	 * 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 token
+	 *                                               in the stack passed in $tokens.
+	 *
+	 * @return int Stack pointer to skip the rest of the file.
+	 */
+	public function process( File $phpcsFile, $stackPtr ) {
+
+		$namespace_token = $phpcsFile->findNext( T_NAMESPACE, $stackPtr );
+		if ( $namespace_token === false ) {
+			// No namespace found, fall through to parent sniff.
+			return parent::process( $phpcsFile, $stackPtr );
+		}
+
+		$tokens = $phpcsFile->getTokens();
+
+		$next_non_empty = $phpcsFile->findNext( Tokens::$emptyTokens, ( $namespace_token + 1 ), null, true );
+		if ( $next_non_empty === false
+			|| $tokens[ $next_non_empty ]['code'] === T_SEMICOLON
+			|| $tokens[ $next_non_empty ]['code'] === T_OPEN_CURLY_BRACKET
+			|| $tokens[ $next_non_empty ]['code'] === T_NS_SEPARATOR
+		) {
+			// Either live coding, global namespace (i.e. not really namespaced) or namespace operator.
+			// Fall through to parent sniff.
+			return parent::process( $phpcsFile, $stackPtr );
+		}
+
+		$comment_start = $phpcsFile->findNext( T_WHITESPACE, ( $stackPtr + 1 ), $namespace_token, true );
+
+		if ( $tokens[ $comment_start ]['code'] === T_DOC_COMMENT_OPEN_TAG ) {
+			$phpcsFile->addWarning(
+				'A file containing a (named) namespace declaration does not need a file docblock',
+				$comment_start,
+				'Unnecessary'
+			);
+		}
+
+		return ( $phpcsFile->numTokens + 1 );
+	}
+}

Yoast/Sniffs/ControlStructures/IfElseDeclarationSniff.php

@@ -1,11 +1,4 @@
 <?php
-/**
- * YoastCS\Yoast\Sniffs\ControlStructures\IfElseDeclarationSniff.
- *
- * @package Yoast\YoastCS
- * @author  Juliette Reinders Folmer
- * @license https://opensource.org/licenses/MIT MIT
- */
 
 namespace YoastCS\Yoast\Sniffs\ControlStructures;
 

Yoast/Sniffs/Files/FileNameSniff.php

@@ -1,11 +1,4 @@
 <?php
-/**
- * YoastCS\Yoast\Sniffs\Files\FileNameSniff.
- *
- * @package Yoast\YoastCS
- * @author  Juliette Reinders Folmer
- * @license https://opensource.org/licenses/MIT MIT
- */
 
 namespace YoastCS\Yoast\Sniffs\Files;
 

Yoast/Sniffs/Files/TestDoublesSniff.php

@@ -1,11 +1,4 @@
 <?php
-/**
- * YoastCS\Yoast\Sniffs\Files\TestDoublesSniff.
- *
- * @package Yoast\YoastCS
- * @author  Juliette Reinders Folmer
- * @license https://opensource.org/licenses/MIT MIT
- */
 
 namespace YoastCS\Yoast\Sniffs\Files;
 

Yoast/Sniffs/Namespaces/NamespaceDeclarationSniff.php

@@ -0,0 +1,111 @@
+<?php
+
+namespace YoastCS\Yoast\Sniffs\Namespaces;
+
+use PHP_CodeSniffer\Sniffs\Sniff;
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Util\Tokens;
+
+/**
+ * Verify namespace declarations.
+ *
+ * This sniff:
+ * - Forbids the use of namespace declarations without a namespace name.
+ * - Forbids the use of scoped namespace declarations.
+ * - Forbids having more than one namespace declaration in a file.
+ *
+ * {@internal This sniff might be a good candidate for pulling upstream in PHPCS
+ * itself. An issue to that effect should be opened to see if there is interest.}}
+ *
+ * @package Yoast\YoastCS
+ * @author  Juliette Reinders Folmer
+ *
+ * @since   1.2.0
+ */
+class NamespaceDeclarationSniff implements Sniff {
+
+	/**
+	 * Returns an array of tokens this test wants to listen for.
+	 *
+	 * @return array
+	 */
+	public function register() {
+		return array(
+			T_OPEN_TAG,
+		);
+	}
+
+	/**
+	 * 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 token
+	 *                                               in the stack passed in $tokens.
+	 *
+	 * @return int Stack pointer to skip the rest of the file.
+	 */
+	public function process( File $phpcsFile, $stackPtr ) {
+
+		$tokens = $phpcsFile->getTokens();
+
+		$found_declaration = array();
+
+		while ( ( $stackPtr = $phpcsFile->findNext( T_NAMESPACE, ( $stackPtr + 1 ) ) ) !== false ) {
+
+			$next_non_empty = $phpcsFile->findNext( Tokens::$emptyTokens, ( $stackPtr + 1 ), null, true );
+			if ( $next_non_empty === false ) {
+				// Live coding or parse error.
+				break;
+			}
+
+			if ( $tokens[ $next_non_empty ]['code'] === T_NS_SEPARATOR ) {
+				// Not a namespace declaration, but the use of the namespace keyword as operator.
+				continue;
+			}
+
+			// OK, found a namespace declaration.
+			$statements[] = $stackPtr;
+
+			if ( isset( $tokens[ $stackPtr ]['scope_condition'] )
+				&& $tokens[ $stackPtr ]['scope_condition'] === $stackPtr
+			) {
+				// Scoped namespace declaration.
+				$phpcsFile->addError(
+					'Scoped namespace declarations are not allowed.',
+					$stackPtr,
+					'ScopedForbidden'
+				);
+			}
+
+			if ( $tokens[ $next_non_empty ]['code'] === T_SEMICOLON
+				|| $tokens[ $next_non_empty ]['code'] === T_OPEN_CURLY_BRACKET
+			) {
+				// Namespace declaration without namespace name (= global namespace).
+				$phpcsFile->addError(
+					'Namespace declarations without a namespace name are not allowed.',
+					$stackPtr,
+					'NoNameForbidden'
+				);
+			}
+		}
+
+		$count = count( $statements );
+		if ( $count > 1 ) {
+			$data = array(
+				$count,
+				$tokens[ $statements[0] ]['line'],
+			);
+
+			for ( $i = 1; $i < $count; $i++ ) {
+				$phpcsFile->addError(
+					'There should be only one namespace declaration per file. Found %d namespace declarations. The first declaration was found on line %d',
+					$statements[ $i ],
+					'MultipleFound',
+					$data
+				);
+			}
+		}
+
+		return ( $phpcsFile->numTokens + 1 );
+	}
+}

Yoast/Sniffs/WhiteSpace/FunctionSpacingSniff.php

@@ -1,11 +1,4 @@
 <?php
-/**
- * YoastCS\Yoast\Sniffs\WhiteSpace\FunctionSpacingSniff.
- *
- * @package Yoast\YoastCS
- * @author  Juliette Reinders Folmer
- * @license https://opensource.org/licenses/MIT MIT
- */
 
 namespace YoastCS\Yoast\Sniffs\WhiteSpace;
 

Yoast/Tests/Commenting/CodeCoverageIgnoreDeprecatedUnitTest.php

@@ -1,10 +1,4 @@
 <?php
-/**
- * Unit test class for the Yoast Coding Standard.
- *
- * @package Yoast\YoastCS
- * @license https://opensource.org/licenses/MIT MIT
- */
 
 namespace YoastCS\Yoast\Tests\Commenting;
 

Yoast/Tests/Commenting/FileCommentUnitTest.1.inc

@@ -0,0 +1,22 @@
+<?php
+/**
+ * File Comment for a file without a namespace.
+ *
+ * For the purposes of the unit test, the docblock here needs to comply with the
+ * complete Squiz file comment rules as the ruleset is not taken into account
+ * when unit testing sniffs.
+ *
+ * @package    Some\Package
+ * @subpackage Something\Else
+ * @author     Squiz Pty Ltd <products@squiz.net>
+ * @copyright  2018 Squiz Pty Ltd (ABN 77 084 670 600)
+ */
+
+/**
+ * Class docblock.
+ */
+class Testing {
+	public function test() {
+		echo namespace\SomeClass::$static_property; // This is not a namespace declaration, but use of the namespace operator.
+	}
+}

Yoast/Tests/Commenting/FileCommentUnitTest.10.inc

@@ -0,0 +1,9 @@
+<?php
+
+namespace {
+
+	/**
+	 * Class docblock. A namespace keyword without actual namespace defaults to global namespace, so a file comment is needed, but missing.
+	 */
+	class Testing {}
+}

Yoast/Tests/Commenting/FileCommentUnitTest.2.inc

@@ -0,0 +1,6 @@
+<?php
+
+/**
+ * Class docblock. No namespace, file comment is needed, but missing.
+ */
+class Testing {}

Yoast/Tests/Commenting/FileCommentUnitTest.3.inc

@@ -0,0 +1,8 @@
+<?php
+
+namespace Yoast\Plugin\Sub;
+
+/**
+ * Class docblock. A file docblock is not needed in a namespaced file.
+ */
+class Testing {}

Yoast/Tests/Commenting/FileCommentUnitTest.4.inc

@@ -0,0 +1,13 @@
+<?php
+/**
+ * File Comment for a file WITH a namespace. This should be flagged as unnecessary.
+ *
+ * @package Some\Package
+ */
+
+namespace Yoast\Plugin\Sub;
+
+/**
+ * Class docblock.
+ */
+class Testing {}

Yoast/Tests/Commenting/FileCommentUnitTest.5.inc

@@ -0,0 +1,17 @@
+<?php
+
+namespace Yoast\Plugin\Sub {
+
+	/**
+	 * Class docblock. A file docblock is not needed in a namespaced file, even when it contains scoped namespaces.
+	 */
+	class Testing {}
+}
+
+namespace Yoast\Plugin\Bub {
+
+	/**
+	 * Class docblock.
+	 */
+	class Testing {}
+}

Yoast/Tests/Commenting/FileCommentUnitTest.6.inc

@@ -0,0 +1,22 @@
+<?php
+/**
+ * File Comment for a file with one or more SCOPED namespace(s). This should be flagged as unnecessary.
+ *
+ * @package Some\Package
+ */
+
+namespace Yoast\Plugin\Sub {
+
+	/**
+	 * Class docblock.
+	 */
+	class Testing {}
+}
+
+namespace Yoast\Plugin\Bub {
+
+	/**
+	 * Class docblock.
+	 */
+	class Testing {}
+}