Ruleset::expandRulesetReference(): test handling "homepath" references

Co-authored-by: Dan Wallis <[email protected]>

Author: jrfnl

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/Fixtures/FakeHomePath/src/MyStandard/Sniffs/Category/ValidSniff.php

@@ -0,0 +1,25 @@
+<?php
+/**
+ * Test fixture.
+ *
+ * @see \PHP_CodeSniffer\Tests\Core\Ruleset\ExpandRulesetReferenceHomePathTest
+ */
+
+namespace FakeHomePath\MyStandard\Sniffs\Category;
+
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\Sniff;
+
+class ValidSniff implements Sniff
+{
+
+    public function register()
+    {
+        return [T_CLASS];
+    }
+
+    public function process(File $phpcsFile, $stackPtr)
+    {
+        // Do something.
+    }
+}

tests/Core/Ruleset/Fixtures/FakeHomePath/src/MyStandard/ruleset.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="MyStandard" namespace="FakeHomePath\MyStandard" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+</ruleset>