Universal/EnumCaseName: new sniff to verify PascalCase enum case names

Add the `Universal.NamingConventions.EnumCaseName` sniff which verifies that
enum case names are declared using PascalCase, as required by PER Coding Style
2.0, section 9.

The sniff registers `T_ENUM_CASE` and checks the following case name with
`Common::isCamelCaps()` in strict class-format mode, so a name must start with
an uppercase letter and must not contain consecutive uppercase letters.

Fixes 444

Author: rodrigoprimo

Universal/Docs/NamingConventions/EnumCaseNameStandard.xml

@@ -0,0 +1,29 @@
+<?xml version="1.0"?>
+<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
+    title="Enum Case Name"
+    >
+    <standard>
+    <![CDATA[
+    Enum case declarations must use PascalCase capitalization.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Enum case name in PascalCase.">
+        <![CDATA[
+enum Suit {
+    case <em>Hearts</em>;
+    case <em>JsonValue</em>;
+}
+        ]]>
+        </code>
+        <code title="Invalid: Enum case name not in PascalCase.">
+        <![CDATA[
+enum Suit {
+    case <em>hearts</em>;
+    case <em>JSONValue</em>;
+}
+        ]]>
+        </code>
+    </code_comparison>
+</documentation>

Universal/Sniffs/NamingConventions/EnumCaseNameSniff.php

@@ -0,0 +1,73 @@
+<?php
+/**
+ * PHPCSExtra, a collection of sniffs and standards for use with PHP_CodeSniffer.
+ *
+ * @package   PHPCSExtra
+ * @copyright 2020 PHPCSExtra Contributors
+ * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
+ * @link      https://github.com/PHPCSStandards/PHPCSExtra
+ */
+
+namespace PHPCSExtra\Universal\Sniffs\NamingConventions;
+
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\Sniff;
+use PHP_CodeSniffer\Util\Common;
+use PHP_CodeSniffer\Util\Tokens;
+
+/**
+ * Verifies that enum case names are declared using PascalCase.
+ *
+ * PascalCase is interpreted strictly: a name must start with an uppercase letter and must not
+ * contain two consecutive uppercase letters, so "JsonValue" is accepted while "JSONValue" is
+ * not.
+ *
+ * @since 1.6.0
+ */
+final class EnumCaseNameSniff implements Sniff
+{
+
+    /**
+     * Registers the tokens that this sniff wants to listen for.
+     *
+     * @since 1.6.0
+     *
+     * @return array<int|string>
+     */
+    public function register()
+    {
+        return [\T_ENUM_CASE];
+    }
+
+    /**
+     * Processes this sniff, when one of its tokens is encountered.
+     *
+     * @since 1.6.0
+     *
+     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
+     * @param int                         $stackPtr  The position of the current token in the token stack.
+     *
+     * @return void
+     */
+    public function process(File $phpcsFile, $stackPtr)
+    {
+        $tokens = $phpcsFile->getTokens();
+
+        $caseNamePtr = $phpcsFile->findNext(Tokens::$emptyTokens, ($stackPtr + 1), null, true);
+        if ($caseNamePtr === false || $tokens[$caseNamePtr]['code'] !== \T_STRING) {
+            // Live coding/parse error.
+            return;
+        }
+
+        $caseName = $tokens[$caseNamePtr]['content'];
+
+        if (Common::isCamelCaps($caseName, true) === false) {
+            $phpcsFile->addError(
+                'Enum case name "%s" is not in PascalCase',
+                $caseNamePtr,
+                'Invalid',
+                [$caseName]
+            );
+        }
+    }
+}

Universal/Tests/NamingConventions/EnumCaseNameUnitTest.1.inc

@@ -0,0 +1,36 @@
+<?php
+
+/*
+ * Valid enum case names (PascalCase).
+ */
+
+enum ValidCaseNames {
+    case Hearts;
+    case DiamondsRed;
+    case Base64Url;
+    case /* comment */ Spades;
+    case
+        // Name on the next line.
+        Clubs;
+}
+
+enum ValidBackedEnum: string {
+    case A = 'A';
+}
+
+/*
+ * Invalid enum case names.
+ */
+
+enum InvalidCaseNames {
+    case diamondsRed;
+    case diamonds_red;
+    case HEARTS;
+    case
+        // Name on the next line.
+        Base64URL;
+}
+
+enum InvalidBackedEnum: int {
+    case _Hidden = 2;
+}

Universal/Tests/NamingConventions/EnumCaseNameUnitTest.2.inc

@@ -0,0 +1,7 @@
+<?php
+
+// Intentional parse error (incomplete enum case declaration).
+// This should be the only test in the file.
+
+enum Incomplete {
+    case

Universal/Tests/NamingConventions/EnumCaseNameUnitTest.3.inc

@@ -0,0 +1,8 @@
+<?php
+
+// Intentional parse error (enum case keyword followed by a non-name token).
+// This should be the only test in the file.
+
+enum Incomplete {
+    case ;
+}

Universal/Tests/NamingConventions/EnumCaseNameUnitTest.php

@@ -0,0 +1,58 @@
+<?php
+/**
+ * PHPCSExtra, a collection of sniffs and standards for use with PHP_CodeSniffer.
+ *
+ * @package   PHPCSExtra
+ * @copyright 2020 PHPCSExtra Contributors
+ * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
+ * @link      https://github.com/PHPCSStandards/PHPCSExtra
+ */
+
+namespace PHPCSExtra\Universal\Tests\NamingConventions;
+
+use PHP_CodeSniffer\Tests\Standards\AbstractSniffTestCase;
+
+/**
+ * Unit test class for the EnumCaseName sniff.
+ *
+ * @covers PHPCSExtra\Universal\Sniffs\NamingConventions\EnumCaseNameSniff
+ *
+ * @since 1.6.0
+ */
+final class EnumCaseNameUnitTest extends AbstractSniffTestCase
+{
+
+    /**
+     * Returns the lines where errors should occur.
+     *
+     * @param string $testFile The name of the file being tested.
+     *
+     * @return array<int, int> Key is the line number, value is the number of expected errors.
+     */
+    public function getErrorList($testFile = '')
+    {
+        switch ($testFile) {
+            case 'EnumCaseNameUnitTest.1.inc':
+                return [
+                    26 => 1,
+                    27 => 1,
+                    28 => 1,
+                    31 => 1,
+                    35 => 1,
+                ];
+
+            default:
+                return [];
+        }
+    }
+
+    /**
+     * Returns the lines where warnings should occur.
+     *
+     * @return array<int, int> Key is the line number, value is the number of expected warnings.
+     */
+    public function getWarningList()
+    {
+        return [];
+    }
+}