From ffc7b50e4be43d73c523ba4166710d5944dcb03b Mon Sep 17 00:00:00 2001
From: Sergey Biryukov <sergeybiryukov@git.wordpress.org>
Date: Fri, 15 Sep 2023 09:06:23 +0000
Subject: [PATCH] Coding Standards: Improve organization of the WPCS-based
 PHPCS ruleset.

This commit:
* Adds section headers to the ruleset file.
* Organizes all directives in their respective sections.

No functional changes.

Props jrf.
See #59161.

git-svn-id: https://develop.svn.wordpress.org/trunk@56593 602fd350-edb4-49c9-b593-d223f7449a82
---
 phpcs.xml.dist | 365 +++++++++++++++++++++++++++----------------------
 1 file changed, 202 insertions(+), 163 deletions(-)

diff --git a/phpcs.xml.dist b/phpcs.xml.dist
index b497b16cfc..a4a7fd6328 100644
--- a/phpcs.xml.dist
+++ b/phpcs.xml.dist
@@ -2,6 +2,13 @@
 <ruleset name="WordPress Coding Standards">
 	<description>Apply WordPress Coding Standards to all Core files</description>
 
+	<!--
+	#############################################################################
+	COMMAND LINE ARGUMENTS
+	https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-Ruleset
+	#############################################################################
+	-->
+
 	<!-- Only scan PHP files. -->
 	<arg name="extensions" value="php"/>
 
@@ -23,81 +30,15 @@
 	<!-- Show sniff codes in all reports. -->
 	<arg value="ps"/>
 
+	<!--
+	#############################################################################
+	FILE SELECTION
+	Set which files will be subject to the scans executed using this ruleset.
+	#############################################################################
+	-->
+
 	<file>.</file>
 
-	<rule ref="WordPress-Core"/>
-	<rule ref="WordPress.CodeAnalysis.EmptyStatement"/>
-
-	<!-- These rules are being set as warnings instead of errors, so we can error check the entire codebase. -->
-	<rule ref="WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase">
-		<type>warning</type>
-	</rule>
-	<rule ref="WordPress.DB.PreparedSQL.InterpolatedNotPrepared">
-		<type>warning</type>
-	</rule>
-	<rule ref="WordPress.DB.PreparedSQL.NotPrepared">
-		<type>warning</type>
-	</rule>
-	<rule ref="WordPress.Files.FileName.InvalidClassFileName">
-		<type>warning</type>
-	</rule>
-
-	<rule ref="WordPress.NamingConventions.ValidVariableName">
-		<properties>
-			<property name="customPropertiesWhitelist" type="array">
-				<!-- From database structure queries. -->
-				<element value="Collation"/>
-				<element value="Column_name"/>
-				<element value="Default"/>
-				<element value="Extra"/>
-				<element value="Field"/>
-				<element value="Index_type"/>
-				<element value="Key"/>
-				<element value="Key_name"/>
-				<element value="Msg_text"/>
-				<element value="Non_unique"/>
-				<element value="Null"/>
-				<element value="Sub_part"/>
-				<element value="Type"/>
-				<!-- From plugin/theme data. -->
-				<element value="authorAndUri"/>
-				<element value="Name"/>
-				<element value="Version"/>
-				<!-- From the result of wp_xmlrpc_server::wp_getPageList(). -->
-				<element value="dateCreated"/>
-
-				<!-- From DOMDocument. -->
-				<element value="childNodes"/>
-				<element value="firstChild"/>
-				<element value="formatOutput"/>
-				<element value="lastChild"/>
-				<element value="nodeName"/>
-				<element value="nodeType"/>
-				<element value="parentNode"/>
-				<element value="preserveWhiteSpace"/>
-				<element value="textContent"/>
-				<!-- From PHPMailer. -->
-				<element value="AltBody"/>
-				<element value="Body"/>
-				<element value="CharSet"/>
-				<element value="ContentType"/>
-				<element value="Encoding"/>
-				<element value="Hostname"/>
-				<element value="mailHeader"/>
-				<element value="MIMEBody"/>
-				<element value="MIMEHeader"/>
-				<element value="Sender"/>
-				<element value="Subject"/>
-				<!-- From PHPUnit_Util_Getopt. -->
-				<element value="longOptions"/>
-				<!-- From POP3. -->
-				<element value="ERROR"/>
-				<!-- From ZipArchive. -->
-				<element value="numFiles"/>
-			</property>
-		</properties>
-	</rule>
-
 	<!-- Exclude the build folder in the current directory. -->
 	<exclude-pattern type="relative">^build/*</exclude-pattern>
 
@@ -165,80 +106,50 @@
 	<!-- Themes except the twenty* themes. -->
 	<exclude-pattern>/src/wp-content/themes/(?!twenty)*</exclude-pattern>
 
-	<!-- Allow the WP DB Class and related tests for usage of direct database access functions. -->
-	<rule ref="WordPress.DB.RestrictedFunctions">
-		<exclude-pattern>/src/wp-includes/class-wpdb\.php</exclude-pattern>
-		<exclude-pattern>/tests/phpunit/tests/db/charset\.php</exclude-pattern>
-	</rule>
 
-	<!-- Allow the WP DB related tests for issues with prepared SQL placeholders
-		 (as the handling of those are being tested). -->
-	<rule ref="WordPress.DB.PreparedSQLPlaceholders.UnfinishedPrepare">
-		<exclude-pattern>/tests/phpunit/tests/db\.php</exclude-pattern>
+	<!--
+	#############################################################################
+	SET UP THE RULESET
+	#############################################################################
+	-->
+
+	<rule ref="WordPress-Core"/>
+	<rule ref="WordPress.CodeAnalysis.EmptyStatement"/>
+
+	<!-- Enforce no parenthesis for language constructs, and only one space immediately after.
+		 Including this rule is temporary until it is moved from the WordPress-Extra ruleset to
+		 the WordPress-Core ruleset upstream.
+	-->
+	<rule ref="PEAR.Files.IncludingFile.BracketsNotRequired">
+		<type>warning</type>
 	</rule>
-	<rule ref="WordPress.DB.PreparedSQLPlaceholders.UnsupportedPlaceholder">
-		<exclude-pattern>/tests/phpunit/tests/db\.php</exclude-pattern>
+	<rule ref="PEAR.Files.IncludingFile.UseRequire">
+		<type>warning</type>
 	</rule>
-	<rule ref="WordPress.DB.PreparedSQLPlaceholders.UnescapedLiteral">
-		<exclude-pattern>/tests/phpunit/tests/db\.php</exclude-pattern>
+	<rule ref="PEAR.Files.IncludingFile.UseRequireOnce">
+		<type>warning</type>
+	</rule>
+	<rule ref="Squiz.WhiteSpace.LanguageConstructSpacing"/>
+
+
+	<!--
+	#############################################################################
+	SNIFF-SPECIFIC CONFIGURATION
+	#############################################################################
+	-->
+
+	<!-- These rules are being set as warnings instead of errors, so we can error check the entire codebase. -->
+	<rule ref="WordPress.DB.PreparedSQL.InterpolatedNotPrepared">
+		<type>warning</type>
 	</rule>
 	<rule ref="WordPress.DB.PreparedSQL.NotPrepared">
-		<exclude-pattern>/tests/phpunit/tests/admin/includesSchema\.php</exclude-pattern>
-		<exclude-pattern>/tests/phpunit/tests/multisite/site\.php</exclude-pattern>
+		<type>warning</type>
+	</rule>
+	<rule ref="WordPress.Files.FileName.InvalidClassFileName">
+		<type>warning</type>
 	</rule>
-
-	<!-- Allow non-snake-case vars & properties for block-related classes. -->
 	<rule ref="WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase">
-		<exclude-pattern>/src/wp-includes/class-wp-block-parser\.php</exclude-pattern>
-		<exclude-pattern>/src/wp-includes/class-wp-block-parser-block\.php</exclude-pattern>
-	</rule>
-	<rule ref="WordPress.NamingConventions.ValidVariableName.PropertyNotSnakeCase">
-		<exclude-pattern>/src/wp-includes/class-wp-block-parser-block\.php</exclude-pattern>
-	</rule>
-	<rule ref="WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase">
-		<exclude-pattern>/src/wp-includes/class-wp-block-parser-block\.php</exclude-pattern>
-	</rule>
-
-	<!-- Allow the I18n functions file for issues identified by the I18n sniff
-		 (such as calling the low-level translate() function). -->
-	<rule ref="WordPress.WP.I18n">
-		<exclude-pattern>/src/wp-includes/l10n\.php</exclude-pattern>
-		<exclude-pattern>/tests/phpunit/tests/l10n\.php</exclude-pattern>
-		<exclude-pattern>/tests/phpunit/tests/l10n/loadTextdomainJustInTime\.php</exclude-pattern>
-	</rule>
-
-	<!-- Translator comments aren't needed in unit tests. -->
-	<rule ref="WordPress.WP.I18n.MissingTranslatorsComment">
-		<exclude-pattern>/tests/*</exclude-pattern>
-	</rule>
-
-	<rule ref="Generic.Functions.FunctionCallArgumentSpacing">
-		<exclude-pattern>/wp-config\.php</exclude-pattern>
-		<exclude-pattern>/wp-config-sample\.php</exclude-pattern>
-		<exclude-pattern>/wp-tests-config\.php</exclude-pattern>
-		<exclude-pattern>/wp-tests-config-sample\.php</exclude-pattern>
-	</rule>
-
-	<!-- Exclude checking of line endings when reporting errors, but fix them when running phpcbf.
-		 Git and SVN manage these pretty well cross-platform as "native".
-		 Allow configuration files. -->
-	<rule ref="Generic.Files.LineEndings">
-		<exclude-pattern>/wp-config\.php</exclude-pattern>
-		<exclude-pattern>/wp-config-sample\.php</exclude-pattern>
-		<exclude phpcs-only="true" name="Generic.Files.LineEndings"/>
-	</rule>
-
-	<!-- WPCS1620: template.php isn't a template tag file. -->
-	<rule ref="WordPress.Files.FileName.InvalidTemplateTagFileName">
-		<exclude-pattern>/src/wp-includes/template\.php</exclude-pattern>
-	</rule>
-
-	<!-- WPCS1621: These files are expected to use _ instead of -. -->
-	<rule ref="WordPress.Files.FileName.NotHyphenatedLowercase">
-		<exclude-pattern>/src/_index\.php</exclude-pattern>
-		<exclude-pattern>/src/wp-admin/_index\.php</exclude-pattern>
-		<exclude-pattern>/src/wp-content/themes/twentythirteen/taxonomy-post_format\.php</exclude-pattern>
-		<exclude-pattern>/src/wp-content/themes/twentyfourteen/taxonomy-post_format\.php</exclude-pattern>
+		<type>warning</type>
 	</rule>
 
 	<!-- Allow test classes for select sniffs. -->
@@ -282,6 +193,62 @@
 		</properties>
 	</rule>
 
+	<rule ref="WordPress.NamingConventions.ValidVariableName">
+		<properties>
+			<property name="customPropertiesWhitelist" type="array">
+				<!-- From database structure queries. -->
+				<element value="Collation"/>
+				<element value="Column_name"/>
+				<element value="Default"/>
+				<element value="Extra"/>
+				<element value="Field"/>
+				<element value="Index_type"/>
+				<element value="Key"/>
+				<element value="Key_name"/>
+				<element value="Msg_text"/>
+				<element value="Non_unique"/>
+				<element value="Null"/>
+				<element value="Sub_part"/>
+				<element value="Type"/>
+				<!-- From plugin/theme data. -->
+				<element value="authorAndUri"/>
+				<element value="Name"/>
+				<element value="Version"/>
+				<!-- From the result of wp_xmlrpc_server::wp_getPageList(). -->
+				<element value="dateCreated"/>
+
+				<!-- From DOMDocument. -->
+				<element value="childNodes"/>
+				<element value="firstChild"/>
+				<element value="formatOutput"/>
+				<element value="lastChild"/>
+				<element value="nodeName"/>
+				<element value="nodeType"/>
+				<element value="parentNode"/>
+				<element value="preserveWhiteSpace"/>
+				<element value="textContent"/>
+				<!-- From PHPMailer. -->
+				<element value="AltBody"/>
+				<element value="Body"/>
+				<element value="CharSet"/>
+				<element value="ContentType"/>
+				<element value="Encoding"/>
+				<element value="Hostname"/>
+				<element value="mailHeader"/>
+				<element value="MIMEBody"/>
+				<element value="MIMEHeader"/>
+				<element value="Sender"/>
+				<element value="Subject"/>
+				<!-- From PHPUnit_Util_Getopt. -->
+				<element value="longOptions"/>
+				<!-- From POP3. -->
+				<element value="ERROR"/>
+				<!-- From ZipArchive. -->
+				<element value="numFiles"/>
+			</property>
+		</properties>
+	</rule>
+
 	<rule ref="WordPress.PHP.NoSilencedErrors">
 		<properties>
 			<property name="custom_whitelist" type="array">
@@ -304,42 +271,43 @@
 		</properties>
 	</rule>
 
-	<!-- Enforce no parenthesis for language constructs, and only one space immediately after.
-		 Including this rule is temporary until it is moved from the WordPress-Extra ruleset to
-		 the WordPress-Core ruleset upstream.
+
+	<!--
+	#############################################################################
+	SELECTIVE EXCLUSIONS
+	Exclude specific files for specific sniffs and/or exclude sub-groups in sniffs.
+	
+	These exclusions are listed ordered by alphabetic sniff name.
+	#############################################################################
 	-->
-	<rule ref="PEAR.Files.IncludingFile.BracketsNotRequired">
-		<type>warning</type>
-	</rule>
-	<rule ref="PEAR.Files.IncludingFile.UseRequire">
-		<type>warning</type>
-	</rule>
-	<rule ref="PEAR.Files.IncludingFile.UseRequireOnce">
-		<type>warning</type>
-	</rule>
-	<rule ref="Squiz.WhiteSpace.LanguageConstructSpacing"/>
 
-	<!-- Assignments in while conditions are a valid method of looping over iterables. -->
-	<rule ref="WordPress.CodeAnalysis.AssignmentInCondition.FoundInWhileCondition">
-		<exclude-pattern>*</exclude-pattern>
+	<!-- Exclude checking of line endings when reporting errors, but fix them when running phpcbf.
+		 Git and SVN manage these pretty well cross-platform as "native".
+		 Allow configuration files. -->
+	<rule ref="Generic.Files.LineEndings">
+		<exclude-pattern>/wp-config\.php</exclude-pattern>
+		<exclude-pattern>/wp-config-sample\.php</exclude-pattern>
+		<exclude phpcs-only="true" name="Generic.Files.LineEndings"/>
 	</rule>
 
-	<!-- Exclude the unit tests from select sniffs. -->
-	<rule ref="WordPress.Files.FileName.NotHyphenatedLowercase">
-		<exclude-pattern>/tests/phpunit/tests/*</exclude-pattern>
+	<rule ref="Generic.Functions.FunctionCallArgumentSpacing">
+		<exclude-pattern>/wp-config\.php</exclude-pattern>
+		<exclude-pattern>/wp-config-sample\.php</exclude-pattern>
+		<exclude-pattern>/wp-tests-config\.php</exclude-pattern>
+		<exclude-pattern>/wp-tests-config-sample\.php</exclude-pattern>
 	</rule>
+
 	<rule ref="PEAR.NamingConventions.ValidClassName.Invalid">
 		<exclude-pattern>/tests/phpunit/tests/*</exclude-pattern>
-	</rule>
-
-	<!-- Exclude some old classes that cannot be renamed, as it would break back compat. -->
-	<rule ref="PEAR.NamingConventions.ValidClassName.Invalid">
+		<!-- Exclude some old classes that cannot be renamed, as it would break back compat. -->
 		<exclude-pattern>/src/wp-admin/includes/class-wp-filesystem-ftpsockets\.php</exclude-pattern>
 		<exclude-pattern>/src/wp-includes/class-wp-oembed\.php</exclude-pattern>
 		<exclude-pattern>/src/wp-includes/class-wp-oembed-controller\.php</exclude-pattern>
 		<exclude-pattern>/src/wp-includes/class-wp-xmlrpc-server\.php</exclude-pattern>
 		<exclude-pattern>/src/wp-includes/class-wp-text-diff-renderer-inline\.php</exclude-pattern>
 	</rule>
+
+	<!-- Exclude some old classes that cannot be renamed, as it would break back compat. -->
 	<rule ref="PEAR.NamingConventions.ValidClassName.StartWithCapital">
 		<exclude-pattern>/src/wp-admin/includes/class-wp-list-table-compat\.php</exclude-pattern>
 		<exclude-pattern>/src/wp-includes/class-wp-dependency\.php</exclude-pattern>
@@ -348,6 +316,43 @@
 		<exclude-pattern>/src/wp-includes/class-wpdb\.php</exclude-pattern>
 	</rule>
 
+	<!-- Assignments in while conditions are a valid method of looping over iterables. -->
+	<rule ref="WordPress.CodeAnalysis.AssignmentInCondition.FoundInWhileCondition">
+		<exclude-pattern>*</exclude-pattern>
+	</rule>
+
+	<!-- Allow the WP DB Class and related tests for usage of direct database access functions. -->
+	<rule ref="WordPress.DB.RestrictedFunctions">
+		<exclude-pattern>/src/wp-includes/class-wpdb\.php</exclude-pattern>
+		<exclude-pattern>/tests/phpunit/tests/db/charset\.php</exclude-pattern>
+	</rule>
+
+	<!-- Allow the WP DB related tests for issues with prepared SQL placeholders
+		 (as the handling of those are being tested). -->
+	<rule ref="WordPress.DB.PreparedSQLPlaceholders.UnfinishedPrepare">
+		<exclude-pattern>/tests/phpunit/tests/db\.php</exclude-pattern>
+	</rule>
+	<rule ref="WordPress.DB.PreparedSQLPlaceholders.UnsupportedPlaceholder">
+		<exclude-pattern>/tests/phpunit/tests/db\.php</exclude-pattern>
+	</rule>
+	<rule ref="WordPress.DB.PreparedSQLPlaceholders.UnescapedLiteral">
+		<exclude-pattern>/tests/phpunit/tests/db\.php</exclude-pattern>
+	</rule>
+	<rule ref="WordPress.DB.PreparedSQL.NotPrepared">
+		<exclude-pattern>/tests/phpunit/tests/admin/includesSchema\.php</exclude-pattern>
+		<exclude-pattern>/tests/phpunit/tests/multisite/site\.php</exclude-pattern>
+	</rule>
+
+	<!-- WPCS1620: template.php isn't a template tag file. -->
+	<rule ref="WordPress.Files.FileName.InvalidTemplateTagFileName">
+		<exclude-pattern>/src/wp-includes/template\.php</exclude-pattern>
+	</rule>
+
+	<!-- Exclude the unit tests from select sniffs. -->
+	<rule ref="WordPress.Files.FileName.NotHyphenatedLowercase">
+		<exclude-pattern>/tests/phpunit/tests/*</exclude-pattern>
+	</rule>
+
 	<!-- Exclude some incorrectly named files that won't be renamed. -->
 	<rule ref="WordPress.Files.FileName.InvalidClassFileName">
 		<exclude-pattern>/src/wp-admin/includes/class-wp-list-table-compat\.php</exclude-pattern>
@@ -357,4 +362,38 @@
 		<exclude-pattern>/src/wp-content/themes/twentyfourteen/inc/widgets\.php</exclude-pattern>
 		<exclude-pattern>/src/wp-content/themes/twentyfourteen/inc/featured-content\.php</exclude-pattern>
 	</rule>
+
+	<!-- WPCS1621: These files are expected to use _ instead of -. -->
+	<rule ref="WordPress.Files.FileName.NotHyphenatedLowercase">
+		<exclude-pattern>/src/_index\.php</exclude-pattern>
+		<exclude-pattern>/src/wp-admin/_index\.php</exclude-pattern>
+		<exclude-pattern>/src/wp-content/themes/twentythirteen/taxonomy-post_format\.php</exclude-pattern>
+		<exclude-pattern>/src/wp-content/themes/twentyfourteen/taxonomy-post_format\.php</exclude-pattern>
+	</rule>
+
+	<!-- Allow the I18n functions file for issues identified by the I18n sniff
+		 (such as calling the low-level translate() function). -->
+	<rule ref="WordPress.WP.I18n">
+		<exclude-pattern>/src/wp-includes/l10n\.php</exclude-pattern>
+		<exclude-pattern>/tests/phpunit/tests/l10n\.php</exclude-pattern>
+		<exclude-pattern>/tests/phpunit/tests/l10n/loadTextdomainJustInTime\.php</exclude-pattern>
+	</rule>
+
+	<!-- Translator comments aren't needed in unit tests. -->
+	<rule ref="WordPress.WP.I18n.MissingTranslatorsComment">
+		<exclude-pattern>/tests/*</exclude-pattern>
+	</rule>
+
+	<!-- Allow non-snake-case vars & properties for block-related classes. -->
+	<rule ref="WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase">
+		<exclude-pattern>/src/wp-includes/class-wp-block-parser\.php</exclude-pattern>
+		<exclude-pattern>/src/wp-includes/class-wp-block-parser-block\.php</exclude-pattern>
+	</rule>
+	<rule ref="WordPress.NamingConventions.ValidVariableName.PropertyNotSnakeCase">
+		<exclude-pattern>/src/wp-includes/class-wp-block-parser-block\.php</exclude-pattern>
+	</rule>
+	<rule ref="WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase">
+		<exclude-pattern>/src/wp-includes/class-wp-block-parser-block\.php</exclude-pattern>
+	</rule>
+
 </ruleset>