Ruleset::expandRulesetReference(): add tests

tests/Core/Ruleset/ExpandRulesetReferenceCaseMismatch1Test.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="ExpandRulesetReferenceTest" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+    <!-- Error handling: Case mismatch, will only error on case sensitive OSes.
+         Correct case would be: PSR12.Functions.NullableTypeDeclaration,
+         i.e. matching the case of the standard, category and sniff class name exactly. -->
+    <rule ref="psr12.functions.nullabletypedeclaration"/>
+
+</ruleset>

tests/Core/Ruleset/ExpandRulesetReferenceCaseMismatch2Test.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="ExpandRulesetReferenceTest" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+    <!-- Error handling: Case mismatch, will only error on case sensitive OSes.
+         Correct case would be: PSR12.Functions.ReturnTypeDeclaration - note the capital T in the sniff name,
+         i.e. matching the case of the standard, category and sniff class name exactly. -->
+    <rule ref="PSR12.Functions.ReturntypeDeclaration"/>
+
+</ruleset>

tests/Core/Ruleset/ExpandRulesetReferenceHomePathFailTest.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="ExpandRulesetReferenceHomePathTest" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+    <!-- With a mocked "home" path to an existing directory, this reference should still fail
+         as the underlying subdirectory doesn't exist. -->
+    <rule ref="~/src/MyStandard/Sniffs/DoesntExist/"/>
+
+</ruleset>

tests/Core/Ruleset/ExpandRulesetReferenceHomePathTest.php

@@ -0,0 +1,120 @@
+<?php
+/**
+ * Test the Ruleset::expandRulesetReference() method.
+ *
+ * @author    Juliette Reinders Folmer <[email protected]>
+ * @copyright 2025 PHPCSStandards and contributors
+ * @license   https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
+ */
+
+namespace PHP_CodeSniffer\Tests\Core\Ruleset;
+
+use PHP_CodeSniffer\Ruleset;
+use PHP_CodeSniffer\Tests\ConfigDouble;
+use PHP_CodeSniffer\Tests\Core\Ruleset\AbstractRulesetTestCase;
+
+/**
+ * Test home path handling in the Ruleset::expandRulesetReference() method.
+ *
+ * @covers \PHP_CodeSniffer\Ruleset::expandRulesetReference
+ */
+final class ExpandRulesetReferenceHomePathTest extends AbstractRulesetTestCase
+{
+
+    /**
+     * Original value of the user's home path environment variable.
+     *
+     * @var string|false Path or false is the `HOME` environment variable is not available.
+     */
+    private static $homepath = false;
+
+
+    /**
+     * Store the user's home path.
+     *
+     * @beforeClass
+     *
+     * @return void
+     */
+    protected function storeHomePath()
+    {
+        $this->homepath = getenv('HOME');
+
+    }//end storeHomePath()
+
+
+    /**
+     * Restore the user's home path environment variable in case the test changed it or created it.
+     *
+     * @afterClass
+     *
+     * @return void
+     */
+    protected function restoreHomePath()
+    {
+        if (is_string($this->homepath) === true) {
+            putenv('HOME='.$this->homepath);
+        } else {
+            // Remove the environment variable as it didn't exist before.
+            putenv('HOME');
+        }
+
+    }//end restoreHomePath()
+
+
+    /**
+     * Set the home path to an alternative location.
+     *
+     * @before
+     *
+     * @return void
+     */
+    protected function setHomePath()
+    {
+        $fakeHomePath = __DIR__.DIRECTORY_SEPARATOR.'Fixtures'.DIRECTORY_SEPARATOR.'FakeHomePath';
+        putenv("HOME=$fakeHomePath");
+
+    }//end setHomePath()
+
+
+    /**
+     * Verify that a sniff reference with the magic "home path" placeholder gets expanded correctly
+     * and finds sniffs if the path exists underneath the "home path".
+     *
+     * @return void
+     */
+    public function testHomePathRefGetsExpandedAndFindsSniff()
+    {
+        // Set up the ruleset.
+        $standard = __DIR__.'/ExpandRulesetReferenceHomePathTest.xml';
+        $config   = new ConfigDouble(["--standard=$standard"]);
+        $ruleset  = new Ruleset($config);
+
+        $expected = ['MyStandard.Category.Valid' => 'FakeHomePath\\MyStandard\\Sniffs\\Category\\ValidSniff'];
+
+        $this->assertSame($expected, $ruleset->sniffCodes);
+
+    }//end testHomePathRefGetsExpandedAndFindsSniff()
+
+
+    /**
+     * Verify that a sniff reference with the magic "home path" placeholder gets expanded correctly
+     * and still fails to find sniffs if the path doesn't exists underneath the "home path".
+     *
+     * @return void
+     */
+    public function testHomePathRefGetsExpandedAndThrowsExceptionWhenPathIsInvalid()
+    {
+        // Set up the ruleset.
+        $standard = __DIR__.'/ExpandRulesetReferenceHomePathFailTest.xml';
+        $config   = new ConfigDouble(["--standard=$standard"]);
+
+        $exceptionMessage = 'Referenced sniff "~/src/MyStandard/Sniffs/DoesntExist/" does not exist';
+        $this->expectRuntimeExceptionMessage($exceptionMessage);
+
+        new Ruleset($config);
+
+    }//end testHomePathRefGetsExpandedAndThrowsExceptionWhenPathIsInvalid()
+
+
+}//end class

tests/Core/Ruleset/ExpandRulesetReferenceHomePathTest.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="ExpandRulesetReferenceHomePathTest" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+    <!-- With a mocked "home" path, this reference should work. -->
+    <rule ref="~/src/MyStandard/Sniffs/Category/"/>
+
+</ruleset>

tests/Core/Ruleset/ExpandRulesetReferenceInternalIgnoreTest.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="ExpandRulesetReferenceInternalTest" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+    <config name="installed_paths" value="./tests/Core/Ruleset/Fixtures/Internal/"/>
+
+    <rule ref="Internal.NoCodeFound">
+        <severity>0</severity>
+    </rule>
+
+    <!-- While this references a valid sniff category, it will be ignored anyway as the ref starts with "Internal". -->
+    <rule ref="Internal.Valid"/>
+
+    <!-- Prevent a "no sniff were registered" error. -->
+    <rule ref="Generic.PHP.BacktickOperator"/>
+</ruleset>

tests/Core/Ruleset/ExpandRulesetReferenceInternalStandardTest.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="ExpandRulesetReferenceInternalTest" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+    <config name="installed_paths" value="./tests/Core/Ruleset/Fixtures/Internal/"/>
+
+    <rule ref="Internal"/>
+
+</ruleset>

tests/Core/Ruleset/ExpandRulesetReferenceInternalTest.php

@@ -0,0 +1,66 @@
+<?php
+/**
+ * Test the Ruleset::expandRulesetReference() method.
+ *
+ * @author    Juliette Reinders Folmer <[email protected]>
+ * @copyright 2025 PHPCSStandards and contributors
+ * @license   https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
+ */
+
+namespace PHP_CodeSniffer\Tests\Core\Ruleset;
+
+use PHP_CodeSniffer\Ruleset;
+use PHP_CodeSniffer\Tests\ConfigDouble;
+use PHP_CodeSniffer\Tests\Core\Ruleset\AbstractRulesetTestCase;
+
+/**
+ * Test handling of "internal" references in the Ruleset::expandRulesetReference() method.
+ *
+ * @covers \PHP_CodeSniffer\Ruleset::expandRulesetReference
+ */
+final class ExpandRulesetReferenceInternalTest extends AbstractRulesetTestCase
+{
+
+
+    /**
+     * Verify that a ruleset reference starting with "Internal." (including the dot) doesn't cause any sniffs to be registered.
+     *
+     * @return void
+     */
+    public function testInternalRefDoesNotGetExpanded()
+    {
+        // Set up the ruleset.
+        $standard = __DIR__.'/ExpandRulesetReferenceInternalIgnoreTest.xml';
+        $config   = new ConfigDouble(["--standard=$standard"]);
+        $ruleset  = new Ruleset($config);
+
+        $expected = ['Generic.PHP.BacktickOperator' => 'PHP_CodeSniffer\\Standards\\Generic\\Sniffs\\PHP\\BacktickOperatorSniff'];
+
+        $this->assertSame($expected, $ruleset->sniffCodes);
+
+    }//end testInternalRefDoesNotGetExpanded()
+
+
+    /**
+     * While definitely not recommended, including a standard named "Internal", _does_ allow for sniffs to be registered.
+     *
+     * Note: customizations (exclusions/property setting etc) for individual sniffs may not always be handled correctly,
+     * which is why naming a standard "Internal" is definitely not recommended.
+     *
+     * @return void
+     */
+    public function testInternalStandardDoesGetExpanded()
+    {
+        // Set up the ruleset.
+        $standard = __DIR__.'/ExpandRulesetReferenceInternalStandardTest.xml';
+        $config   = new ConfigDouble(["--standard=$standard"]);
+        $ruleset  = new Ruleset($config);
+
+        $expected = ['Internal.Valid.Valid' => 'Fixtures\\Internal\\Sniffs\\Valid\\ValidSniff'];
+
+        $this->assertSame($expected, $ruleset->sniffCodes);
+
+    }//end testInternalStandardDoesGetExpanded()
+
+
+}//end class

tests/Core/Ruleset/ExpandRulesetReferenceInvalidErrorCode1Test.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="ExpandRulesetReferenceTest" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+    <!-- Error handling: Invalid error code ref - missing standard name. -->
+    <rule ref=".Invalid.Undetermined.Found"/>
+
+</ruleset>

tests/Core/Ruleset/ExpandRulesetReferenceInvalidErrorCode2Test.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="ExpandRulesetReferenceTest" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+    <!-- Error handling: Invalid error code ref - missing category name. -->
+    <rule ref="Standard..Undetermined.Found"/>
+
+</ruleset>

tests/Core/Ruleset/ExpandRulesetReferenceInvalidErrorCode3Test.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="ExpandRulesetReferenceTest" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+    <!-- Error handling: Invalid error code ref - missing sniff name. -->
+    <rule ref="Standard.Invalid..Found"/>
+
+</ruleset>

tests/Core/Ruleset/ExpandRulesetReferenceInvalidHomePathRefTest.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="ExpandRulesetReferenceTest" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+    <!-- This "home path" reference is not going to work, but that's not the point of this test.
+         The point is for the code to, at least, _try_ to resolve it. -->
+    <rule ref="~/src/Standards/Squiz/Sniffs/Files/"/>
+
+</ruleset>

tests/Core/Ruleset/ExpandRulesetReferenceMissingFileTest.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="ExpandRulesetReferenceTest" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+    <!-- This test deliberately includes an XML file which doesn't exist. That is exactly what this test is about. -->
+    <rule ref="./MissingFile.xml"/>
+
+</ruleset>