Merge pull request #4 from PHPCSStandards/feature/add-debug-ruleset

New feature: Debug ruleset and sniff

Author: jrfnl

.gitattributes

@@ -9,6 +9,9 @@
 /.gitignore export-ignore
 /.travis.yml export-ignore
 /phpcs.xml.dist export-ignore
+/phpunit.xml.dist export-ignore
+/phpunit-bootstrap.php export-ignore
+/Debug/Tests export-ignore
 
 #
 # Auto detect text files and perform LF normalization

.gitignore

@@ -2,3 +2,4 @@ vendor/
 composer.lock
 .phpcs.xml
 phpcs.xml
+phpunit.xml

.travis.yml

@@ -13,19 +13,39 @@ cache:
 
 php:
   - 5.4
-  - 7.3
+  - 5.5
+  - 5.6
+  - 7.0
+  - 7.1
+  - 7.2
+
+env:
+  matrix:
+    # `master`
+    - PHPCS_VERSION="dev-master" LINT=1
+    # Lowest supported PHPCS version.
+    # In reality this is 3.0.2, but there is a bug in the unit test runner of that version.
+    - PHPCS_VERSION="3.0.2"
 
 # Define the stages used.
+# For non-PRs, only the sniff and quicktest stages are run.
+# For pull requests and merges, the full script is run (skipping quicktest).
+# Note: for pull requests, "develop" is the base branch name.
+# See: https://docs.travis-ci.com/user/conditions-v1
 stages:
   - name: sniff
+  - name: quicktest
+    if: type = push AND branch NOT IN (master, develop)
   - name: test
+    if: branch IN (master, develop)
 
 jobs:
   fast_finish: true
   include:
     #### SNIFF STAGE ####
     - stage: sniff
       php: 7.3
+      env: PHPCS_VERSION="dev-master"
       addons:
         apt:
           packages:
@@ -36,27 +56,89 @@ jobs:
 
         # Validate the xml file.
         # @link http://xmlsoft.org/xmllint.html
+        - xmllint --noout --schema ./vendor/squizlabs/php_codesniffer/phpcs.xsd ./Debug/ruleset.xml
         - xmllint --noout --schema ./vendor/squizlabs/php_codesniffer/phpcs.xsd ./PHPCSDev/ruleset.xml
 
         # Check the code-style consistency of the xml files.
+        - diff -B ./Debug/ruleset.xml <(xmllint --format "./Debug/ruleset.xml")
         - diff -B ./PHPCSDev/ruleset.xml <(xmllint --format "./PHPCSDev/ruleset.xml")
 
 
+    #### QUICK TEST STAGE ####
+    # This is a much quicker test which only runs the unit tests and linting against the low/high
+    # supported PHP/PHPCS combinations.
+    - stage: quicktest
+      php: 7.3
+      env: PHPCS_VERSION="dev-master" LINT=1
+    - php: 7.2
+      env: PHPCS_VERSION="3.0.2"
+
+    - php: 5.4
+      env: PHPCS_VERSION="dev-master" LINT=1
+    - php: 5.4
+      env: PHPCS_VERSION="3.0.2"
+
+    #### TEST STAGE ####
+    # Additional builds to prevent issues with PHPCS versions incompatible with certain PHP versions.
+    - stage: test
+      php: 7.3
+      env: PHPCS_VERSION="dev-master" LINT=1
+    # PHPCS is only compatible with PHP 7.3 as of version 3.3.1.
+    - php: 7.3
+      env: PHPCS_VERSION="3.3.1"
+    # PHPCS is only compatible with PHP 7.4 as of version 3.5.0.
+    - php: "7.4snapshot"
+      env: PHPCS_VERSION=dev-master"
+
+  allow_failures:
+    # Allow failures for unstable builds.
+    - php: "7.4snapshot"
+
+
 before_install:
   # Speed up build time by disabling Xdebug when its not needed.
   - phpenv config-rm xdebug.ini || echo 'No xdebug config.'
 
+  # On stable PHPCS versions, allow for PHP deprecation notices.
+  # Unit tests don't need to fail on those for stable releases where those issues won't get fixed anymore.
+  - |
+    if [[ "$TRAVIS_BUILD_STAGE_NAME" != "Sniff" && $PHPCS_BRANCH != "dev-master" ]]; then
+      echo 'error_reporting = E_ALL & ~E_DEPRECATED' >> ~/.phpenv/versions/$(phpenv version-name)/etc/conf.d/travis.ini
+    fi
+
   - export XMLLINT_INDENT="    "
 
+  # Set up test environment using Composer.
+  - composer require --no-update --no-scripts squizlabs/php_codesniffer:${PHPCS_VERSION}
+  - |
+    if [[ "$TRAVIS_BUILD_STAGE_NAME" == "Sniff" ]]; then
+      # The sniff stage doesn't run the unit tests, so no need for PHPUnit.
+      composer remove --dev phpunit/phpunit --no-update --no-scripts
+    elif [[ "$PHPCS_VERSION" < "3.1.0" ]]; then
+      # PHPCS < 3.1.0 is not compatible with PHPUnit 6.x.
+      composer require --dev phpunit/phpunit:"^4.0||^5.0" --no-update --no-scripts
+    elif [[ "$PHPCS_VERSION" < "3.2.3" ]]; then
+      # PHPCS < 3.2.3 is not compatible with PHPUnit 7.x.
+      composer require --dev phpunit/phpunit:"^4.0||^5.0||^6.0" --no-update --no-scripts
+    fi
+
   # --prefer-dist will allow for optimal use of the travis caching ability.
   # The Composer PHPCS plugin takes care of setting the installed_paths for PHPCS.
   - composer install --prefer-dist --no-suggest
 
 
 script:
   # Lint PHP files against parse errors.
-  - composer lint
+  - if [[ "$LINT" == "1" ]]; then composer lint; fi
+
+  # Check that any sniffs available are feature complete.
+  # This also acts as an integration test for the feature completeness script,
+  # which is why it is run against various PHP versions and not in the "Sniff" stage.
+  - if [[ "$LINT" == "1" ]]; then composer check-complete; fi
 
-  # Validate the composer.json file on low/high PHP versions.
+  # Validate the composer.json file.
   # @link https://getcomposer.org/doc/03-cli.md#validate
-  - composer validate --no-check-all --strict
+  - if [[ "$LINT" == "1" ]]; then composer validate --no-check-all --strict; fi
+
+  # Run the unit tests.
+  - composer run-tests

Debug/Docs/Debug/TokenListStandard.xml

@@ -0,0 +1,9 @@
+<documentation title="Token List">
+    <standard>
+    <![CDATA[
+    Lists how PHPCS tokenizes code.
+
+    This sniff will not throw any warnings or errors, but is solely intended as a tool for sniff developers.
+    ]]>
+    </standard>
+</documentation>

Debug/Sniffs/Debug/TokenListSniff.php

@@ -0,0 +1,97 @@
+<?php
+/**
+ * PHPCSDevTools, tools for PHP_CodeSniffer sniff developers.
+ *
+ * @package   PHPCSDevTools
+ * @copyright 2019 PHPCSDevTools Contributors
+ * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
+ * @link      https://github.com/PHPCSStandards/PHPCSDevTools
+ */
+
+namespace PHPCSStandards\Debug\Sniffs\Debug;
+
+use PHP_CodeSniffer\Sniffs\Sniff;
+use PHP_CodeSniffer\Files\File;
+
+/**
+ * Lists how PHPCS tokenizes code.
+ *
+ * This sniff will not throw any warnings or errors, but is solely intended
+ * as a tool for sniff developers.
+ *
+ * @since 1.0.0
+ */
+class TokenListSniff implements Sniff
+{
+
+    /**
+     * A list of tokenizers this sniff supports.
+     *
+     * @var array
+     */
+    public $supportedTokenizers = [
+        'PHP',
+        'JS',
+        'CSS',
+    ];
+
+    /**
+     * Returns an array of tokens this test wants to listen for.
+     *
+     * @return array
+     */
+    public function register()
+    {
+        return [
+            \T_OPEN_TAG,
+            \T_OPEN_TAG_WITH_ECHO,
+        ];
+    }
+
+    /**
+     * 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.
+     *
+     * @return void
+     */
+    public function process(File $phpcsFile, $stackPtr)
+    {
+        $tokens = $phpcsFile->getTokens();
+
+        $oldIniValue = \ini_set('xdebug.overload_var_dump', 1);
+
+        echo \PHP_EOL;
+        foreach ($tokens as $ptr => $token) {
+            if (isset($token['length']) === false) {
+                $token['length'] = strlen($token['content']);
+            }
+
+            $content = $token['content'];
+            if ($token['code'] === \T_WHITESPACE
+                || (defined('T_DOC_COMMENT_WHITESPACE')
+                && $token['code'] === \T_DOC_COMMENT_WHITESPACE)
+            ) {
+                if (strpos($token['content'], "\t") !== false) {
+                    $content = str_replace("\t", '\t', $token['content']);
+                }
+                if (isset($token['orig_content'])) {
+                    $content .= ' :: Orig: ' . str_replace("\t", '\t', $token['orig_content']);
+                }
+            }
+
+            echo $ptr, ' :: L', \str_pad($token['line'], 3, '0', \STR_PAD_LEFT), ' :: C', $token['column'],
+                ' :: ', $token['type'], ' :: (', $token['length'], ') :: ', $content, \PHP_EOL;
+        }
+
+        // If necessary, reset the ini setting.
+        if ($oldIniValue !== false) {
+            \ini_set('xdebug.overload_var_dump', $oldIniValue);
+        }
+
+        // Only do this once per file.
+        return ($phpcsFile->numTokens + 1);
+    }
+}

Debug/Tests/Debug/TokenListUnitTest.inc

@@ -0,0 +1 @@
+<?php

Debug/Tests/Debug/TokenListUnitTest.php

@@ -0,0 +1,75 @@
+<?php
+/**
+ * PHPCSDevTools, tools for PHP_CodeSniffer sniff developers.
+ *
+ * @package   PHPCSDevTools
+ * @copyright 2019 PHPCSDevTools Contributors
+ * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
+ * @link      https://github.com/PHPCSStandards/PHPCSDevTools
+ */
+
+namespace PHPCSStandards\Debug\Tests\Debug;
+
+use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
+
+/**
+ * Unit test class for the TokenList sniff.
+ *
+ * @covers PHPCSStandards\Debug\Sniffs\Debug::TokenListSniff
+ *
+ * @since 1.0.0
+ */
+class TokenListUnitTest extends AbstractSniffUnitTest
+{
+
+    /**
+     * Cache any output generated during the test.
+     *
+     * @var string
+     */
+    public static $output = '';
+
+    /**
+     * Sets up this unit test.
+     *
+     * @return void
+     */
+    protected function setUp()
+    {
+        parent::setUp();
+
+        ob_start();
+    }
+
+    /**
+     * Clean up.
+     *
+     * @return void
+     */
+    protected function tearDown()
+    {
+        self::$output = ob_get_flush();
+
+        parent::tearDown();
+    }
+
+    /**
+     * Returns the lines where errors should occur.
+     *
+     * @return array <int line number> => <int number of errors>
+     */
+    public function getErrorList()
+    {
+        return [];
+    }
+
+    /**
+     * Returns the lines where warnings should occur.
+     *
+     * @return array <int line number> => <int number of warnings>
+     */
+    public function getWarningList()
+    {
+        return [];
+    }
+}

Debug/Tests/Debug/TokenListZUnitTest.php

@@ -0,0 +1,39 @@
+<?php
+/**
+ * PHPCSDevTools, tools for PHP_CodeSniffer sniff developers.
+ *
+ * @package   PHPCSDevTools
+ * @copyright 2019 PHPCSDevTools Contributors
+ * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
+ * @link      https://github.com/PHPCSStandards/PHPCSDevTools
+ */
+
+namespace PHPCSStandards\Debug\Tests\Debug;
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Unit test class for the TokenList sniff.
+ *
+ * @covers PHPCSStandards\Debug\Sniffs\Debug::TokenListSniff
+ *
+ * @since 1.0.0
+ */
+class TokenListZUnitTest extends TestCase
+{
+
+    /**
+     * Test the actual output of the TokenList sniff.
+     *
+     * @return void
+     */
+    public function testOutput()
+    {
+        $output = trim(TokenListUnitTest::$output);
+
+        $this->assertNotEmpty($output);
+
+        $expected = '0 :: L001 :: C1 :: T_OPEN_TAG :: (5) :: <?php';
+        $this->assertSame($expected, $output);
+    }
+}

Debug/ruleset.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="Debug" namespace="PHPCSStandards\Debug" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/squizlabs/PHP_CodeSniffer/master/phpcs.xsd">
+
+    <description>Sniffs which can be used as debugging tools for PHPCS developers</description>
+
+</ruleset>