From 3eca7f74422012ee2eec998269ca77f956b6e924 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Mon, 13 Jan 2025 15:32:28 +0100
Subject: [PATCH 1/3] Ruleset::expandRulesetReference(): test handling
 "homepath" references

Co-authored-by: Dan Wallis <dan@wallis.nz>
---
 ...ExpandRulesetReferenceHomePathFailTest.xml |   8 ++
 .../ExpandRulesetReferenceHomePathTest.php    | 120 ++++++++++++++++++
 .../ExpandRulesetReferenceHomePathTest.xml    |   7 +
 .../MyStandard/Sniffs/Category/ValidSniff.php |  25 ++++
 .../FakeHomePath/src/MyStandard/ruleset.xml   |   4 +
 5 files changed, 164 insertions(+)
 create mode 100644 tests/Core/Ruleset/ExpandRulesetReferenceHomePathFailTest.xml
 create mode 100644 tests/Core/Ruleset/ExpandRulesetReferenceHomePathTest.php
 create mode 100644 tests/Core/Ruleset/ExpandRulesetReferenceHomePathTest.xml
 create mode 100644 tests/Core/Ruleset/Fixtures/FakeHomePath/src/MyStandard/Sniffs/Category/ValidSniff.php
 create mode 100644 tests/Core/Ruleset/Fixtures/FakeHomePath/src/MyStandard/ruleset.xml

diff --git a/tests/Core/Ruleset/ExpandRulesetReferenceHomePathFailTest.xml b/tests/Core/Ruleset/ExpandRulesetReferenceHomePathFailTest.xml
new file mode 100644
index 0000000000..803c848de6
--- /dev/null
+++ b/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>
diff --git a/tests/Core/Ruleset/ExpandRulesetReferenceHomePathTest.php b/tests/Core/Ruleset/ExpandRulesetReferenceHomePathTest.php
new file mode 100644
index 0000000000..a644af08c7
--- /dev/null
+++ b/tests/Core/Ruleset/ExpandRulesetReferenceHomePathTest.php
@@ -0,0 +1,120 @@
+<?php
+/**
+ * Test the Ruleset::expandRulesetReference() method.
+ *
+ * @author    Juliette Reinders Folmer <phpcs_nospam@adviesenzo.nl>
+ * @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
diff --git a/tests/Core/Ruleset/ExpandRulesetReferenceHomePathTest.xml b/tests/Core/Ruleset/ExpandRulesetReferenceHomePathTest.xml
new file mode 100644
index 0000000000..8d39a26935
--- /dev/null
+++ b/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>
diff --git a/tests/Core/Ruleset/Fixtures/FakeHomePath/src/MyStandard/Sniffs/Category/ValidSniff.php b/tests/Core/Ruleset/Fixtures/FakeHomePath/src/MyStandard/Sniffs/Category/ValidSniff.php
new file mode 100644
index 0000000000..9346df9eb1
--- /dev/null
+++ b/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.
+    }
+}
diff --git a/tests/Core/Ruleset/Fixtures/FakeHomePath/src/MyStandard/ruleset.xml b/tests/Core/Ruleset/Fixtures/FakeHomePath/src/MyStandard/ruleset.xml
new file mode 100644
index 0000000000..a8c9b1ad8a
--- /dev/null
+++ b/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>

From cef31addeac61436d1fc2935ec65791eaf33518f Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Wed, 29 Jan 2025 00:16:08 +0100
Subject: [PATCH 2/3] Ruleset::expandRulesetReference(): test handling
 "Internal" references

---
 ...pandRulesetReferenceInternalIgnoreTest.xml | 15 +++++
 ...ndRulesetReferenceInternalStandardTest.xml |  8 +++
 .../ExpandRulesetReferenceInternalTest.php    | 66 +++++++++++++++++++
 .../Internal/Sniffs/Valid/ValidSniff.php      | 25 +++++++
 .../Ruleset/Fixtures/Internal/ruleset.xml     | 11 ++++
 5 files changed, 125 insertions(+)
 create mode 100644 tests/Core/Ruleset/ExpandRulesetReferenceInternalIgnoreTest.xml
 create mode 100644 tests/Core/Ruleset/ExpandRulesetReferenceInternalStandardTest.xml
 create mode 100644 tests/Core/Ruleset/ExpandRulesetReferenceInternalTest.php
 create mode 100644 tests/Core/Ruleset/Fixtures/Internal/Sniffs/Valid/ValidSniff.php
 create mode 100644 tests/Core/Ruleset/Fixtures/Internal/ruleset.xml

diff --git a/tests/Core/Ruleset/ExpandRulesetReferenceInternalIgnoreTest.xml b/tests/Core/Ruleset/ExpandRulesetReferenceInternalIgnoreTest.xml
new file mode 100644
index 0000000000..9398e402b7
--- /dev/null
+++ b/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>
diff --git a/tests/Core/Ruleset/ExpandRulesetReferenceInternalStandardTest.xml b/tests/Core/Ruleset/ExpandRulesetReferenceInternalStandardTest.xml
new file mode 100644
index 0000000000..0493e253c6
--- /dev/null
+++ b/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>
diff --git a/tests/Core/Ruleset/ExpandRulesetReferenceInternalTest.php b/tests/Core/Ruleset/ExpandRulesetReferenceInternalTest.php
new file mode 100644
index 0000000000..edac7490d0
--- /dev/null
+++ b/tests/Core/Ruleset/ExpandRulesetReferenceInternalTest.php
@@ -0,0 +1,66 @@
+<?php
+/**
+ * Test the Ruleset::expandRulesetReference() method.
+ *
+ * @author    Juliette Reinders Folmer <phpcs_nospam@adviesenzo.nl>
+ * @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
diff --git a/tests/Core/Ruleset/Fixtures/Internal/Sniffs/Valid/ValidSniff.php b/tests/Core/Ruleset/Fixtures/Internal/Sniffs/Valid/ValidSniff.php
new file mode 100644
index 0000000000..e7a04f495a
--- /dev/null
+++ b/tests/Core/Ruleset/Fixtures/Internal/Sniffs/Valid/ValidSniff.php
@@ -0,0 +1,25 @@
+<?php
+/**
+ * Test fixture.
+ *
+ * @see \PHP_CodeSniffer\Tests\Core\Ruleset\ExpandRulesetReferenceInternalTest
+ */
+
+namespace Fixtures\Internal\Sniffs\Valid;
+
+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.
+    }
+}
diff --git a/tests/Core/Ruleset/Fixtures/Internal/ruleset.xml b/tests/Core/Ruleset/Fixtures/Internal/ruleset.xml
new file mode 100644
index 0000000000..fefcfcb301
--- /dev/null
+++ b/tests/Core/Ruleset/Fixtures/Internal/ruleset.xml
@@ -0,0 +1,11 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="Internal" namespace="Fixtures\Internal" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+    <!--
+    A standard named "Internal" can be included, but individual categories or sniffs from that standard cannot.
+    In other words: standards should not be named "Internal".
+
+    This test fixture helps document and safeguard the current behaviour for standards named "Internal".
+    -->
+
+</ruleset>

From ef411ee1c967c0e2bf19fac96fe11d02887c970d Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Wed, 29 Jan 2025 02:07:22 +0100
Subject: [PATCH 3/3] Ruleset::expandRulesetReference(): add miscellaneous
 tests

Note: test coverage for the `Ruleset::expandRulesetReference()` method will still not be 100% even after the addition of these tests.
* There are some conditions which are specific to running PHPCS via a PHAR file. At this time, the tests are not run with a PHAR file, which means these lines cannot be covered via the tests.
* As for the other uncovered lines/branches: my fantasy ran out and I couldn't come up with a situation which would trigger that code.
    Code archaeology (`git blame`) to find out why the code was introduced unfortunately didn't help.
    This may indicate the code is redundant and can be removed, but this is not certain at this time and leaving the code in place is not harming anyone for now.
    If over time, nobody can come up with a real life situation which would allow us to test those lines, it could be considered to remove them in a future major release to see what breaks....
---
 ...xpandRulesetReferenceCaseMismatch1Test.xml |   9 ++
 ...xpandRulesetReferenceCaseMismatch2Test.xml |   9 ++
 ...dRulesetReferenceInvalidErrorCode1Test.xml |   7 +
 ...dRulesetReferenceInvalidErrorCode2Test.xml |   7 +
 ...dRulesetReferenceInvalidErrorCode3Test.xml |   7 +
 ...RulesetReferenceInvalidHomePathRefTest.xml |   8 ++
 .../ExpandRulesetReferenceMissingFileTest.xml |   7 +
 .../Ruleset/ExpandRulesetReferenceTest.php    | 133 ++++++++++++++++++
 .../Ruleset/ExpandRulesetReferenceTest.xml    |  13 ++
 ...andRulesetReferenceUnknownCategoryTest.xml |  10 ++
 ...ExpandRulesetReferenceUnknownSniffTest.xml |  10 ++
 ...andRulesetReferenceUnknownStandardTest.xml |  10 ++
 .../Sniffs/CheckSomething/ValidSniff.php      |  25 ++++
 .../Ruleset/Fixtures/ExternalA/ruleset.xml    |   4 +
 .../ExternalB/Sniffs/CheckMore/ValidSniff.php |  25 ++++
 .../Ruleset/Fixtures/ExternalB/ruleset.xml    |   4 +
 16 files changed, 288 insertions(+)
 create mode 100644 tests/Core/Ruleset/ExpandRulesetReferenceCaseMismatch1Test.xml
 create mode 100644 tests/Core/Ruleset/ExpandRulesetReferenceCaseMismatch2Test.xml
 create mode 100644 tests/Core/Ruleset/ExpandRulesetReferenceInvalidErrorCode1Test.xml
 create mode 100644 tests/Core/Ruleset/ExpandRulesetReferenceInvalidErrorCode2Test.xml
 create mode 100644 tests/Core/Ruleset/ExpandRulesetReferenceInvalidErrorCode3Test.xml
 create mode 100644 tests/Core/Ruleset/ExpandRulesetReferenceInvalidHomePathRefTest.xml
 create mode 100644 tests/Core/Ruleset/ExpandRulesetReferenceMissingFileTest.xml
 create mode 100644 tests/Core/Ruleset/ExpandRulesetReferenceTest.php
 create mode 100644 tests/Core/Ruleset/ExpandRulesetReferenceTest.xml
 create mode 100644 tests/Core/Ruleset/ExpandRulesetReferenceUnknownCategoryTest.xml
 create mode 100644 tests/Core/Ruleset/ExpandRulesetReferenceUnknownSniffTest.xml
 create mode 100644 tests/Core/Ruleset/ExpandRulesetReferenceUnknownStandardTest.xml
 create mode 100644 tests/Core/Ruleset/Fixtures/ExternalA/Sniffs/CheckSomething/ValidSniff.php
 create mode 100644 tests/Core/Ruleset/Fixtures/ExternalA/ruleset.xml
 create mode 100644 tests/Core/Ruleset/Fixtures/ExternalB/Sniffs/CheckMore/ValidSniff.php
 create mode 100644 tests/Core/Ruleset/Fixtures/ExternalB/ruleset.xml

diff --git a/tests/Core/Ruleset/ExpandRulesetReferenceCaseMismatch1Test.xml b/tests/Core/Ruleset/ExpandRulesetReferenceCaseMismatch1Test.xml
new file mode 100644
index 0000000000..7b22223010
--- /dev/null
+++ b/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>
diff --git a/tests/Core/Ruleset/ExpandRulesetReferenceCaseMismatch2Test.xml b/tests/Core/Ruleset/ExpandRulesetReferenceCaseMismatch2Test.xml
new file mode 100644
index 0000000000..1080c769fa
--- /dev/null
+++ b/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>
diff --git a/tests/Core/Ruleset/ExpandRulesetReferenceInvalidErrorCode1Test.xml b/tests/Core/Ruleset/ExpandRulesetReferenceInvalidErrorCode1Test.xml
new file mode 100644
index 0000000000..f864f35136
--- /dev/null
+++ b/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>
diff --git a/tests/Core/Ruleset/ExpandRulesetReferenceInvalidErrorCode2Test.xml b/tests/Core/Ruleset/ExpandRulesetReferenceInvalidErrorCode2Test.xml
new file mode 100644
index 0000000000..49814db7b5
--- /dev/null
+++ b/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>
diff --git a/tests/Core/Ruleset/ExpandRulesetReferenceInvalidErrorCode3Test.xml b/tests/Core/Ruleset/ExpandRulesetReferenceInvalidErrorCode3Test.xml
new file mode 100644
index 0000000000..439fe9a672
--- /dev/null
+++ b/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>
diff --git a/tests/Core/Ruleset/ExpandRulesetReferenceInvalidHomePathRefTest.xml b/tests/Core/Ruleset/ExpandRulesetReferenceInvalidHomePathRefTest.xml
new file mode 100644
index 0000000000..801ead6dd7
--- /dev/null
+++ b/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>
diff --git a/tests/Core/Ruleset/ExpandRulesetReferenceMissingFileTest.xml b/tests/Core/Ruleset/ExpandRulesetReferenceMissingFileTest.xml
new file mode 100644
index 0000000000..c7d95e431f
--- /dev/null
+++ b/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>
diff --git a/tests/Core/Ruleset/ExpandRulesetReferenceTest.php b/tests/Core/Ruleset/ExpandRulesetReferenceTest.php
new file mode 100644
index 0000000000..adf1d3e32a
--- /dev/null
+++ b/tests/Core/Ruleset/ExpandRulesetReferenceTest.php
@@ -0,0 +1,133 @@
+<?php
+/**
+ * Test the Ruleset::expandRulesetReference() method.
+ *
+ * @author    Juliette Reinders Folmer <phpcs_nospam@adviesenzo.nl>
+ * @copyright 2024 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 various aspects of the Ruleset::expandRulesetReference() method not covered by other tests.
+ *
+ * @covers \PHP_CodeSniffer\Ruleset::expandRulesetReference
+ */
+final class ExpandRulesetReferenceTest extends AbstractRulesetTestCase
+{
+
+
+    /**
+     * Test handling of path references relative to the originally included ruleset.
+     *
+     * @return void
+     */
+    public function testRulesetRelativePathReferences()
+    {
+        // Set up the ruleset.
+        $standard = __DIR__.'/ExpandRulesetReferenceTest.xml';
+        $config   = new ConfigDouble(["--standard=$standard"]);
+        $ruleset  = new Ruleset($config);
+
+        $expected = [
+            'ExternalA.CheckSomething.Valid'              => 'Fixtures\\ExternalA\\Sniffs\\CheckSomething\\ValidSniff',
+            'TestStandard.ValidSniffs.RegisterEmptyArray' => 'Fixtures\\TestStandard\\Sniffs\\ValidSniffs\\RegisterEmptyArraySniff',
+            'ExternalB.CheckMore.Valid'                   => 'Fixtures\\ExternalB\\Sniffs\\CheckMore\\ValidSniff',
+        ];
+
+        $this->assertSame($expected, $ruleset->sniffCodes);
+
+    }//end testRulesetRelativePathReferences()
+
+
+    /**
+     * Test that an exception is thrown if a ruleset contains an unresolvable reference.
+     *
+     * @param string $standard    The standard to use for the test.
+     * @param string $replacement The reference which will be used in the exception message.
+     *
+     * @dataProvider dataUnresolvableReferenceThrowsException
+     *
+     * @return void
+     */
+    public function testUnresolvableReferenceThrowsException($standard, $replacement)
+    {
+        // Set up the ruleset.
+        $standard = __DIR__.'/'.$standard;
+        $config   = new ConfigDouble(["--standard=$standard"]);
+
+        $exceptionMessage = 'Referenced sniff "%s" does not exist';
+        $this->expectRuntimeExceptionMessage(sprintf($exceptionMessage, $replacement));
+
+        new Ruleset($config);
+
+    }//end testUnresolvableReferenceThrowsException()
+
+
+    /**
+     * Data provider.
+     *
+     * @see testUnresolvableReferenceThrowsException()
+     *
+     * @return array<string, array<string, string>>
+     */
+    public static function dataUnresolvableReferenceThrowsException()
+    {
+        $data = [
+            'Referencing a non-existent XML file'                     => [
+                'standard'    => 'ExpandRulesetReferenceMissingFileTest.xml',
+                'replacement' => './MissingFile.xml',
+            ],
+            'Referencing an invalid directory starting with "~"'      => [
+                'standard'    => 'ExpandRulesetReferenceInvalidHomePathRefTest.xml',
+                'replacement' => '~/src/Standards/Squiz/Sniffs/Files/',
+            ],
+            'Referencing an unknown standard'                         => [
+                'standard'    => 'ExpandRulesetReferenceUnknownStandardTest.xml',
+                'replacement' => 'UnknownStandard',
+            ],
+            'Referencing a non-existent category in a known standard' => [
+                'standard'    => 'ExpandRulesetReferenceUnknownCategoryTest.xml',
+                'replacement' => 'TestStandard.UnknownCategory',
+            ],
+            'Referencing a non-existent sniff in a known standard'    => [
+                'standard'    => 'ExpandRulesetReferenceUnknownSniffTest.xml',
+                'replacement' => 'TestStandard.InvalidSniffs.UnknownRule',
+            ],
+            'Referencing an invalid error code - no standard name'    => [
+                'standard'    => 'ExpandRulesetReferenceInvalidErrorCode1Test.xml',
+                'replacement' => '.Invalid.Undetermined.Found',
+            ],
+            'Referencing an invalid error code - no category name'    => [
+                'standard'    => 'ExpandRulesetReferenceInvalidErrorCode2Test.xml',
+                'replacement' => 'Standard..Undetermined.Found',
+            ],
+            'Referencing an invalid error code - no sniff name'       => [
+                'standard'    => 'ExpandRulesetReferenceInvalidErrorCode3Test.xml',
+                'replacement' => 'Standard.Invalid..Found',
+            ],
+        ];
+
+        // Add tests which are only relevant for case-sensitive OSes.
+        if (stripos(PHP_OS, 'WIN') === false) {
+            $data['Referencing an existing sniff, but there is a case mismatch (OS-dependent) [1]'] = [
+                'standard'    => 'ExpandRulesetReferenceCaseMismatch1Test.xml',
+                'replacement' => 'psr12.functions.nullabletypedeclaration',
+            ];
+            $data['Referencing an existing sniff, but there is a case mismatch (OS-dependent) [2]'] = [
+                'standard'    => 'ExpandRulesetReferenceCaseMismatch2Test.xml',
+                'replacement' => 'PSR12.Functions.ReturntypeDeclaration',
+            ];
+        }
+
+        return $data;
+
+    }//end dataUnresolvableReferenceThrowsException()
+
+
+}//end class
diff --git a/tests/Core/Ruleset/ExpandRulesetReferenceTest.xml b/tests/Core/Ruleset/ExpandRulesetReferenceTest.xml
new file mode 100644
index 0000000000..aaa23759ee
--- /dev/null
+++ b/tests/Core/Ruleset/ExpandRulesetReferenceTest.xml
@@ -0,0 +1,13 @@
+<?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">
+
+    <!-- Including a single sniff via a ruleset relative file ref. -->
+    <rule ref="./Fixtures/ExternalA/Sniffs/CheckSomething/ValidSniff.php"/>
+
+    <!-- Including a category of sniffs via a ruleset relative directory ref. -->
+    <rule ref="./Fixtures/TestStandard/Sniffs/ValidSniffs"/>
+
+    <!-- Including a complete standard via a ruleset relative directory ref. -->
+    <rule ref="./Fixtures/ExternalB"/>
+
+</ruleset>
diff --git a/tests/Core/Ruleset/ExpandRulesetReferenceUnknownCategoryTest.xml b/tests/Core/Ruleset/ExpandRulesetReferenceUnknownCategoryTest.xml
new file mode 100644
index 0000000000..26f8c8491b
--- /dev/null
+++ b/tests/Core/Ruleset/ExpandRulesetReferenceUnknownCategoryTest.xml
@@ -0,0 +1,10 @@
+<?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">
+
+    <config name="installed_paths" value="./tests/Core/Ruleset/Fixtures/TestStandard/"/>
+
+    <!-- This test deliberately includes a non-existent category in a known standard (which won't resolve).
+         That is exactly what this test is about. -->
+    <rule ref="TestStandard.UnknownCategory"/>
+
+</ruleset>
diff --git a/tests/Core/Ruleset/ExpandRulesetReferenceUnknownSniffTest.xml b/tests/Core/Ruleset/ExpandRulesetReferenceUnknownSniffTest.xml
new file mode 100644
index 0000000000..8b9b3ad197
--- /dev/null
+++ b/tests/Core/Ruleset/ExpandRulesetReferenceUnknownSniffTest.xml
@@ -0,0 +1,10 @@
+<?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">
+
+    <config name="installed_paths" value="./tests/Core/Ruleset/Fixtures/TestStandard/"/>
+
+    <!-- This test deliberately includes a non-existent sniff in a known standard (which won't resolve).
+         That is exactly what this test is about. -->
+    <rule ref="TestStandard.InvalidSniffs.UnknownRule"/>
+
+</ruleset>
diff --git a/tests/Core/Ruleset/ExpandRulesetReferenceUnknownStandardTest.xml b/tests/Core/Ruleset/ExpandRulesetReferenceUnknownStandardTest.xml
new file mode 100644
index 0000000000..8563f860dc
--- /dev/null
+++ b/tests/Core/Ruleset/ExpandRulesetReferenceUnknownStandardTest.xml
@@ -0,0 +1,10 @@
+<?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">
+
+    <config name="installed_paths" value="./tests/Core/Ruleset/Fixtures/TestStandard/"/>
+
+    <!-- This test deliberately includes an unknown standard which won't resolve.
+         That is exactly what this test is about. -->
+    <rule ref="UnknownStandard"/>
+
+</ruleset>
diff --git a/tests/Core/Ruleset/Fixtures/ExternalA/Sniffs/CheckSomething/ValidSniff.php b/tests/Core/Ruleset/Fixtures/ExternalA/Sniffs/CheckSomething/ValidSniff.php
new file mode 100644
index 0000000000..51061e3b5e
--- /dev/null
+++ b/tests/Core/Ruleset/Fixtures/ExternalA/Sniffs/CheckSomething/ValidSniff.php
@@ -0,0 +1,25 @@
+<?php
+/**
+ * Test fixture.
+ *
+ * @see \PHP_CodeSniffer\Tests\Core\Ruleset\ExpandRulesetReferenceTest
+ */
+
+namespace Fixtures\ExternalA\Sniffs\CheckSomething;
+
+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.
+    }
+}
diff --git a/tests/Core/Ruleset/Fixtures/ExternalA/ruleset.xml b/tests/Core/Ruleset/Fixtures/ExternalA/ruleset.xml
new file mode 100644
index 0000000000..a4d929c6c7
--- /dev/null
+++ b/tests/Core/Ruleset/Fixtures/ExternalA/ruleset.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="ExternalA" namespace="Fixtures\ExternalA" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+</ruleset>
diff --git a/tests/Core/Ruleset/Fixtures/ExternalB/Sniffs/CheckMore/ValidSniff.php b/tests/Core/Ruleset/Fixtures/ExternalB/Sniffs/CheckMore/ValidSniff.php
new file mode 100644
index 0000000000..1584f70504
--- /dev/null
+++ b/tests/Core/Ruleset/Fixtures/ExternalB/Sniffs/CheckMore/ValidSniff.php
@@ -0,0 +1,25 @@
+<?php
+/**
+ * Test fixture.
+ *
+ * @see \PHP_CodeSniffer\Tests\Core\Ruleset\ExpandRulesetReferenceTest
+ */
+
+namespace Fixtures\ExternalB\Sniffs\CheckMore;
+
+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.
+    }
+}
diff --git a/tests/Core/Ruleset/Fixtures/ExternalB/ruleset.xml b/tests/Core/Ruleset/Fixtures/ExternalB/ruleset.xml
new file mode 100644
index 0000000000..2f4447ee36
--- /dev/null
+++ b/tests/Core/Ruleset/Fixtures/ExternalB/ruleset.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="ExternalB" namespace="Fixtures\ExternalB" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+</ruleset>