Broaden detection for plugin entrypoint files

CHANGELOG.md

@@ -5,7 +5,8 @@ and fill in the contents as you go. This simplifies later release management. --
 
 ## 2.3.0
 
-- Do not lint PHP within `build/` and `dist/` build directories
+- Broaden relaxation of "must be named namespace.php" check for plugin entrypoint files to allow the patterns `<plugin-name>/plugin.php` or `<plugin-name>/<plugin-name>.php` in both regular and mu-plugin folders. #343
+- Do not lint PHP within `build/` and `dist/` build directories #342
 
 ## 2.2.1
 

HM/Sniffs/Files/FunctionFileNameSniff.php

@@ -8,7 +8,7 @@
  * Sniff to check for namespaced functions are in `namespace.php`.
  */
 class FunctionFileNameSniff implements Sniff {
-	use MuPluginFileTrait;
+	use PluginEntryPointTrait;
 
 	public function register() {
 		return array( T_FUNCTION );
@@ -27,8 +27,8 @@ public function process( File $phpcsFile, $stackPtr ) {
 			return;
 		}
 
-		if ( $this->is_single_file_mu_plugin( $phpcsFile->getFileName() ) ) {
-			// Single-file plugins cannot be split into a namespace.php file.
+		if ( $this->is_plugin_entry_point( $phpcsFile ) ) {
+			// Plugin entry points cannot be split into a namespace.php file.
 			return;
 		}
 

HM/Sniffs/Files/NamespaceDirectoryNameSniff.php

@@ -8,7 +8,7 @@
  * Namespaced things must be in directories matching the namespace.
  */
 class NamespaceDirectoryNameSniff implements Sniff {
-	use MuPluginFileTrait;
+	use PluginEntryPointTrait;
 
 	/**
 	 * Returns an array of tokens this test wants to listen for.
@@ -52,8 +52,8 @@ public function process( File $phpcsFile, $stackPtr ) {
 			$directory = str_replace( DIRECTORY_SEPARATOR, '/', $directory );
 		}
 
-		if ( $this->is_single_file_mu_plugin( $full ) ) {
-			// Single-file mu-plugins will naturally never have an inc/ directory.
+		if ( $this->is_plugin_entry_point( $phpcsFile ) ) {
+			// Plugin entry points will naturally never have an inc/ directory.
 			return;
 		}
 

HM/Sniffs/Files/PluginEntryPointTrait.php

@@ -0,0 +1,60 @@
+<?php
+namespace HM\Sniffs\Files;
+
+use PHP_CodeSniffer\Files\File;
+
+/**
+ * Shared helper for detecting plugin entry points.
+ *
+ * We support two patterns:
+ *
+ * "Single-file mu-plugins" live as a direct child of a `mu-plugins/` directory
+ * (or `client-mu-plugins/`, on VIP) and encapsulate a complete plugin within
+ * one single PHP file.
+ *
+ * A plugin entrypoint may alternatively live nested within a plugin folder,
+ * conventionally named after its parent folder or else called plugin.php.
+ * These ordinary plugin entrypoints can live within `plugins/`, `mu-plugins/`
+ * or `client-mu-plugins/` alike.
+ *
+ * Both are useful patterns to support, and should be exempt from certain rules:
+ * entrypoint files can't be split into an inc/ directory and collide or lose
+ * meaning if renamed to namespace.php.
+ */
+trait PluginEntryPointTrait {
+	/**
+	 * Is the file being checked a plugin entry point?
+	 *
+	 * @param File $phpcsFile The file being scanned.
+	 * @return bool True if the file is a single-file mu-plugin or a nested plugin entry point.
+	 */
+	protected function is_plugin_entry_point( File $phpcsFile ) {
+		$path = $phpcsFile->getFilename();
+
+		// Normalize the directory separator across operating systems.
+		if ( DIRECTORY_SEPARATOR !== '/' ) {
+			$path = str_replace( DIRECTORY_SEPARATOR, '/', $path );
+		}
+
+		// Naming a file plugin.php conventionally signals it's a plugin entrypoint.
+		if ( basename( $path ) === 'plugin.php' ) {
+			return true;
+		}
+
+		// Single-file mu-plugin: a direct child of (client-)mu-plugins/.
+		if ( preg_match( '#/(?:client-)?mu-plugins/[^/]+\.php$#', $path ) ) {
+			return true;
+		}
+
+		// Nested entry point: the conventionally named main file directly
+		// inside a plugin's own folder, under plugins/, mu-plugins/ or
+		// client-mu-plugins/. Anything deeper is ordinary plugin code.
+		if ( ! preg_match( '#/(?:(?:client-)?mu-)?plugins/([^/]+)/([^/]+)\.php$#', $path, $matches ) ) {
+			return false;
+		}
+
+		// Check for conventional pattern <plugin-name>/<plugin-name>.php.
+		[ , $dir, $file ] = $matches;
+		return $file === $dir;
+	}
+}

HM/Tests/Files/FunctionFileNameUnitTest.php

@@ -52,6 +52,11 @@ public function getErrorList() {
 			// Single-file mu-plugins can't all be named namespace.php.
 			'my-plugin.php',
 			'my-client-plugin.php',
+			// Nested plugin entry points are exempt too -- in plugins/ as well
+			// as mu-plugins/ -- when named <dir>/<dir>.php or <dir>/plugin.php.
+			'sub-plugin.php',
+			'plugin.php',
+			'plugin-name.php',
 		];
 		if ( in_array( $file, $pass, true ) ) {
 			return [];

HM/Tests/Files/FunctionFileNameUnitTest/mu-plugins/plugin-name/plugin-name.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace HM\Coding\Standards\Plugin_Named_After_Dir;
+
+function foo() {}

HM/Tests/Files/FunctionFileNameUnitTest/mu-plugins/with-plugin-file/plugin.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace HM\Coding\Standards\With_Plugin_File;
+
+function foo() {}

HM/Tests/Files/FunctionFileNameUnitTest/plugins/plugin-name/plugin-name.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace HM\Coding\Standards\Standalone;
+
+function foo() {}

HM/Tests/Files/FunctionFileNameUnitTest/plugins/with-plugin-file/plugin.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace HM\Coding\Standards\With_Plugin_File;
+
+function foo() {}

HM/Tests/Files/NamespaceDirectoryNameUnitTest.php

@@ -55,6 +55,10 @@ public function getErrorList() {
 			// Single-file mu-plugins are exempt from the directory structure rules.
 			'mu-plugin.php',
 			'client-mu-plugin.php',
+			// Nested plugin entry points are exempt too -- in plugins/ as well
+			// as mu-plugins/ -- when named <dir>/<dir>.php or <dir>/plugin.php.
+			'plugin.php',
+			'plugin-name.php',
 		];
 		if ( in_array( $file, $pass, true ) ) {
 			return [];

HM/Tests/Files/NamespaceDirectoryNameUnitTest/mu-plugins/plugin-name/plugin-name.php

@@ -0,0 +1,3 @@
+<?php
+
+namespace HM\Coding\Standards\Plugin_Named_After_Dir;

HM/Tests/Files/NamespaceDirectoryNameUnitTest/mu-plugins/with-plugin-file/plugin.php

@@ -0,0 +1,3 @@
+<?php
+
+namespace HM\Coding\Standards\With_Plugin_File;

HM/Tests/Files/NamespaceDirectoryNameUnitTest/plugins/plugin-name/plugin-name.php

@@ -0,0 +1,3 @@
+<?php
+
+namespace HM\Coding\Standards\Standalone;

HM/Tests/Files/NamespaceDirectoryNameUnitTest/plugins/with-plugin-file/plugin.php

@@ -0,0 +1,3 @@
+<?php
+
+namespace HM\Coding\Standards\With_Plugin_File;