NamingConventions/NamespaceName: new "missing prefix" error, bug fix and other improvements

[jrfnl]

NamingConventions/NamespaceName: minor documentation tweaks

NamingConventions/NamespaceName: minor tweak

Ignore an untestable line for code coverage analysis.

NamingConventions/NamespaceName: tweak the test case files

• Tie the test description comments closer together with the settings being tested.
• Consolidate "mismatch" tests.
  No need for two test files. One path translates to one valid namespace (depending on settings), so all possible cases for one path can always be tested within one test case file.
• Remove parse error from mismatch test.
• Add one additional test case to the src/sub-b/path-translation-src-sub-b.inc test case file.

NamingConventions/NamespaceName: add tests with PHP 8.0+ namespace names with reserved keywords

These tests should pass without issue since PHPCS 3.7.1, though would have failed on PHP < 8.0 prior to that.

Includes adding note to some pre-existing tests about the PHP 8.0 change.

NamingConventions/NamespaceName: implement use of the PHPCSUtils Namespaces::getDeclaredName() method

... to replace a large chunk of code.

This also fixes a bug where the original code did not correctly determine the namespace name if it contained a parse error, while the PHPCSUtils method does handle this more robustly.

As a consequence of this change, one test expectation changes, but as that test is for a parse error, I'm not concerned about that.

NamingConventions/NamespaceName: use PHPCSUtils TextStrings::stripQuotes()

NamingConventions/NamespaceName: no need to double trailing slashes

Slashes are already being added to the $name two lines earlier, so no need to do it again.

NamingConventions/NamespaceName: make non-interface methods private

As the sniff class is now final (since PR #319), there is no need for any protected methods, so let's make these private.

NamingConventions/NamespaceName: throw an error if a prefix is expected, but not used

The sniff expects a prefixes property to be passed from a ruleset and for a valid prefix to be used in a namespace name, however, this was not checked.

This commit adds a new error to the sniff which will be thrown if at least one valid prefix has been passed and no valid prefix was used in the namespace name.

Includes unit tests + some minor updates to pre-existing tests which will now also throw this error.

NamingConventions/NamespaceName: make the "incorrect namespace name" error more informative

When no prefix was matched, the error would previously read Expected: "[Plugin\Prefix]..."; Found: "...".
However, if there is only one known valid prefix, we can already replace the [Plugin\Prefix] with the expected prefix.

Fixed now.

The effect of this fix can be seen in the messages thrown by the unit tests, but can't be safeguarded via the tests at this time.

NamingConventions/NamespaceName: allow for more variation is test dir layouts

As the test directory layout for the plugins will change from:

- .\
  - integration-tests\
    - doubles\
  - tests\
    - doubles\

... to ....

- .\
  - tests\
    - unit\
      - doubles\
    - wp\
      - doubles\

.. the sniff needs to widen its allowance for these extra levels in the namespace name.

This commit implements this additional allowance.

While the current solution should possibly be made more code base agnostic via a custom property, for now, this solution will do.

Includes additional tests.

NamingConventions/NamespaceName: improve handling of unconventional directory names

As things were, the NamespaceName sniff would translate the namespace to the expected directory path and then compare the directory paths.

This is the wrong way round as this sniff is about namespace names, not directory names, so the directory name should be translated to a namespace name and then compared with the actual namespace name instead.

Along the same lines, there was the possibility that the sniff would recommend an "Expected" namespace name which would be a parse error/invalid syntax in PHP.

This commit fixes both these issues.

The commit also adds an extra error for directory names which can't (for a certain definition of "can't") be translated to a valid namespace name.

Includes additional unit tests demonstrating the problem.

Note: if the name in use in the file is causing a problematic parse error (like in the test with the # in the namespace name), the sniff will stay silent. This is the normal behaviour for PHPCS check when encountering parse errors.

NamingConventions/NamespaceName: implement use of new PathHelper class

NamingConventions/NamespaceName: improve path handling

This changes the src_directory property handling.

Originally, the file paths would always be stripped down to a relative path in relation to the basepath.
Now, the src_directory path comparison(s) will always be based on the absolute path, including the basepath.

This should have a small performance benefit, in that some of the path manipulation is moved to the validate_src_directory() method, the logic of which under normal circumstances, will only be run once, while the process() method is run for every namespace keyword encountered.

This also implements the use of some additional functions from the PathHelper and the PathValidationHelper classes.

Includes updating a pre-existing test to pass duplicate excluded files in different ways.

[coveralls]

coverage: 99.294% (+0.2%) from 99.095%
when pulling d2837d1 on JRF/yoastcs-namespacename-various-improvements
into 7ce39da on develop.