Core: add section about namespace declaration rules with select new sniffs

[jrfnl]

Namespace declarations

Each part of a namespace name should consist of capitalized words separated by underscores.

Namespace declarations should have exactly one blank line before the declaration and at least one blank line after.

There should be only one namespace declaration per file, and it should be at the top of the file. Namespace declarations using curly brace syntax are not allowed. Explicit global namespace declaration (namespace declaration without name) are also not allowed.

Refs:

• https://make.wordpress.org/core/2020/03/20/updating-the-coding-standards-for-modern-php/ - Namespace declarations section
• https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#namespace-declarations
• Add namespace declaration section wpcs-docs#97
• Proposal: Add rules about (formatting of) namespace declarations #1763
• New Universal.Namespaces.DisallowCurlyBraceSyntax sniff PHPCSStandards/PHPCSExtra#4
• New Universal.Namespaces.OneDeclarationPerFile sniff PHPCSStandards/PHPCSExtra#6
• New Universal.Namespaces.DisallowDeclarationWithoutName sniff PHPCSStandards/PHPCSExtra#50

Notes:

• The "Each part of a namespace name should consist of capitalized words separated by underscores" rule needs a new dedicated sniff.
  An issue will need to be opened about this in WPCS. The corresponding issue in PHPCSExtra is Sniff to enforce naming conventions for namespace names PHPCSStandards/PHPCSExtra#231
• The "Namespace declarations should have exactly one blank line before the declaration and at least one blank line after" will probably also need a new sniff.
  My research shows the following:
  • The PSR2.Namespaces.NamespaceDeclaration sniff, which is included in Extra can sort of cover the "after" part, as in: it check for exactly one blank line after, which is close to, but not exactly what we want.
  • The PSR12.Files.FileHeader sniff can check both "before" and "after", but will also, again, check for exactly one blank line.
    The problem with that sniff is that it currently is "all or nothing", it does not have modular error codes, so we cannot ignore some other things from that sniff (requires blank line between PHP open tag and file docblock), which makes it problematic to include the sniff.
    If upstream PR PSR12/FileHeader: make "SpacingAfter" and "SpacingInside" errorcodes modular squizlabs/PHP_CodeSniffer#2729 would (finally) be merged, we could reconsider adding that sniff though.
• As for the "... it (the namespace declaration) should be at the top of the file" rule. I do not believe we need to actively check for this.
  With the "only one namespace declaration per file" rule being enforced, placing the namespace declaration anywhere else than at the top of the file would be a parse error.

Other notes:

• The "namespace keyword should be lowercase" part, as mentioned in the Make post, is already covered by the Generic.PHP.LowerCaseKeyword sniff.
• The "There should be exactly one space between the namespace keyword and the start of the namespace name" part, as mentioned in the Make post, is already covered by the Generic.WhiteSpace.LanguageConstructSpacing sniff, which was moved to Core in Core: move rules related to include/require statements from Extra to Core #2097.
• The "namespace names in a namespace declaration should not start with a leading backslash \", as well as the "There should be no whitespace or comments within the name part of the namespace declaration.", as mentioned in the Make post, are things which can (and should) be flagged by PHPCompatibility 10.0.

Closes #1763

[GaryJones]

✅