[FEATURE] Add a utility class to calculate selector specificity

Calculating and caching the specificity of a selector is a
different concern than representing a selector, and it deserves
to be in its own class.

This also helps solve the problem of selectors having keep
their specificity cached and in sync with the selector itself.

(We'll have a later change that changes `Selector` to use the
new class.)

Author: oliverklee

src/Property/DependencyCalculator.php

@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\Property;
+
+/**
+ * Utility class to calculate the specificity of a CSS selector.
+ *
+ * The results are cached to avoid recalculating the specificity of the same selector multiple times.
+ *
+ * @internal
+ */
+final class DependencyCalculator
+{
+    /**
+     * regexp for specificity calculations
+     *
+     * @var non-empty-string
+     */
+    private const NON_ID_ATTRIBUTES_AND_PSEUDO_CLASSES_RX = '/
+        (\\.[\\w]+)                   # classes
+        |
+        \\[(\\w+)                     # attributes
+        |
+        (\\:(                         # pseudo classes
+            link|visited|active
+            |hover|focus
+            |lang
+            |target
+            |enabled|disabled|checked|indeterminate
+            |root
+            |nth-child|nth-last-child|nth-of-type|nth-last-of-type
+            |first-child|last-child|first-of-type|last-of-type
+            |only-child|only-of-type
+            |empty|contains
+        ))
+        /ix';
+
+    /**
+     * regexp for specificity calculations
+     *
+     * @var non-empty-string
+     */
+    private const ELEMENTS_AND_PSEUDO_ELEMENTS_RX = '/
+        ((^|[\\s\\+\\>\\~]+)[\\w]+   # elements
+        |
+        \\:{1,2}(                    # pseudo-elements
+            after|before|first-letter|first-line|selection
+        ))
+        /ix';
+
+    /**
+     * @var array<string, int<0, max>>
+     */
+    private static $specificityCache = [];
+
+    /**
+     * @return int<0, max>
+     */
+    public static function calculateSpecificity(string $selector): int
+    {
+        if (!isset(self::$specificityCache[$selector])) {
+            $a = 0;
+            /// @todo should exclude \# as well as "#"
+            $aMatches = null;
+            $b = \substr_count($selector, '#');
+            $c = \preg_match_all(self::NON_ID_ATTRIBUTES_AND_PSEUDO_CLASSES_RX, $selector, $aMatches);
+            $d = \preg_match_all(self::ELEMENTS_AND_PSEUDO_ELEMENTS_RX, $selector, $aMatches);
+            self::$specificityCache[$selector] = ($a * 1000) + ($b * 100) + ($c * 10) + $d;
+        }
+
+        return self::$specificityCache[$selector];
+    }
+}

tests/Unit/Property/DependencyCalculatorTest.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\Tests\Unit\Property;
+
+use PHPUnit\Framework\TestCase;
+use Sabberworm\CSS\Property\DependencyCalculator;
+
+/**
+ * @covers \Sabberworm\CSS\Property\DependencyCalculator
+ */
+final class DependencyCalculatorTest extends TestCase
+{
+    /**
+     * @return array<string, array{0: non-empty-string, 1: int<0, max>}>
+     */
+    public static function provideSelectorsAndSpecificities(): array
+    {
+        return [
+            'element' => ['a', 1],
+            'element and descendant with pseudo-selector' => ['ol li::before', 3],
+            'class' => ['.highlighted', 10],
+            'element with class' => ['li.green', 11],
+            'class with pseudo-selector' => ['.help:hover', 20],
+            'ID' => ['#file', 100],
+            'ID and descendant class' => ['#test .help', 110],
+        ];
+    }
+
+    /**
+     * @test
+     *
+     * @param non-empty-string $selector
+     * @param int<0, max> $expectedSpecificity
+     *
+     * @dataProvider provideSelectorsAndSpecificities
+     */
+    public function calculateSpecificityReturnsSpecificityForProvidedSelector(
+        string $selector,
+        int $expectedSpecificity
+    ): void {
+        self::assertSame($expectedSpecificity, DependencyCalculator::calculateSpecificity($selector));
+    }
+}