refactor: remove unused tokens from components (#1159)

Author: thorbrink

.phpunit.result.cache

@@ -1,5 +1,6 @@
 #!/bin/php
 <?php
+
 // Only allow run from cli.
 if (php_sapi_name() !== 'cli') {
     exit(0);
@@ -9,7 +10,7 @@
 $buildCommands = [
     'npm ci --no-progress --no-audit',
     'npm run build',
-    'composer install --prefer-dist --no-progress'
+    'composer install --prefer-dist --no-progress',
 ];
 
 // Files and directories not suitable for prod to be removed.
@@ -34,6 +35,7 @@
     'postcss.config.js',
     'setup.sh',
     'webpack.config.js',
+    'source/components/Tests',
 ];
 
 $dirName = basename(dirname(__FILE__));
@@ -69,14 +71,14 @@ function executeCommand($command)
 {
     $proc = popen("$command 2>&1 ; echo Exit status : $?", 'r');
 
-    $liveOutput     = '';
+    $liveOutput = '';
     $completeOutput = '';
 
     while (!feof($proc)) {
-        $liveOutput     = fread($proc, 4096);
+        $liveOutput = fread($proc, 4096);
         $completeOutput = $completeOutput . $liveOutput;
         print $liveOutput;
-        @ flush();
+        @flush();
     }
 
     pclose($proc);

build.php

@@ -53,7 +53,7 @@
 		}
 	},
 	"scripts": {
-		"test": "vendor/bin/phpunit",
+		"test": "vendor/bin/phpunit --testdox",
 		"test:filter": "vendor/bin/phpunit --filter",
 		"lint": "vendor/bin/mago lint",
 		"fix": "vendor/bin/mago lint --format-after-fix --fix",

composer.json

@@ -12,5 +12,8 @@
         <testsuite name="validators">
             <directory suffix="Test.php">source/validators/Tests</directory>
         </testsuite>
+        <testsuite name="components">
+            <directory suffix="Test.php">source/components/Tests</directory>
+        </testsuite>
     </testsuites>
 </phpunit>

phpunit.xml

@@ -0,0 +1,104 @@
+<?php
+
+namespace MunicipioStyleGuide\Components\Tests;
+
+use PHPUnit\Framework\TestCase;
+
+class UnusedTokensTest extends TestCase
+{
+    private const SHADOW_TOKEN = 'shadow';
+    private const SHADOW_REQUIRED_TOKENS = ['shadow-amount', 'shadow-color'];
+    private const TOKEN_EXCEPTIONS = self::SHADOW_REQUIRED_TOKENS;
+
+    /**
+     * @testdox component utilizes all tokens declared in component.json
+     * @dataProvider componentFilesProvider
+     */
+    public function testComponentUtilizeAllTokens(string $component, string $tokenFile, string $styleFile): void
+    {
+        $tokens = self::extractTokensFromTokenFile($tokenFile);
+        $styleFileContents = (string) file_get_contents($styleFile);
+
+        self::assertShadowDependenciesAreDeclared($tokens, $styleFileContents, $component);
+        $unusedTokens = self::findUnusedTokens($tokens, $styleFileContents, self::TOKEN_EXCEPTIONS);
+
+        $errorMessage = sprintf("Component '%s' has declared but unused tokens in %s:%s- %s", $component, $styleFile, PHP_EOL, implode(PHP_EOL . '- ', $unusedTokens));
+        $this->assertEmpty($unusedTokens, $errorMessage);
+    }
+
+    private static function assertShadowDependenciesAreDeclared(
+        array $tokens,
+        string $styleFileContents,
+        string $component,
+    ): void {
+        if (!self::styleFileUsesToken($styleFileContents, self::SHADOW_TOKEN)) {
+            return;
+        }
+
+        $missingTokens = array_values(array_diff(self::SHADOW_REQUIRED_TOKENS, $tokens));
+
+        self::assertEmpty(
+            $missingTokens,
+            sprintf(
+                "Component '%s' is missing required shadow tokens: %s",
+                $component,
+                implode(', ', $missingTokens),
+            ),
+        );
+    }
+
+    private static function findUnusedTokens(array $tokens, string $styleFileContents, array $excludedTokens): array
+    {
+        $unusedTokens = [];
+
+        foreach ($tokens as $token) {
+            if (in_array($token, $excludedTokens, true)) {
+                continue;
+            }
+
+            if (!self::styleFileUsesToken($styleFileContents, $token)) {
+                $unusedTokens[] = $token;
+            }
+        }
+
+        return $unusedTokens;
+    }
+
+    private static function styleFileUsesToken(string $styleFileContents, string $token): bool
+    {
+        // Match tokens.use/get(<anything>, '<token>'[, <optional args>])
+        $pattern = '/tokens\.(use|get)\s*\([^,]+,\s*[\'\"]' . preg_quote($token, '/') . '[\'\"](?:\s*,[^)]*)?\s*\)/m';
+
+        return preg_match($pattern, $styleFileContents) === 1;
+    }
+
+    private static function extractTokensFromTokenFile(string $tokenFile): array
+    {
+        $content = (string) file_get_contents($tokenFile);
+        $data = json_decode($content, true);
+
+        if (!is_array($data)) {
+            return [];
+        }
+
+        return $data['tokens'] ?? [];
+    }
+
+    public static function componentFilesProvider(): \Generator
+    {
+        $componentsDir = __DIR__ . '/../';
+        $componentExceptions = ['Tests']; // Exclude test directory itself
+        $components = array_filter(scandir($componentsDir), function ($item) use ($componentsDir, $componentExceptions) {
+            return is_dir($componentsDir . $item) && !in_array($item, ['.', '..', ...$componentExceptions], true);
+        });
+
+        foreach ($components as $component) {
+            $tokenFile = $componentsDir . $component . '/component.json';
+            $styleFile = $componentsDir . $component . '/style.scss';
+
+            yield $component => [$component, $tokenFile, $styleFile];
+        }
+
+        return;
+    }
+}

source/components/Tests/UnusedTokensTest.php

@@ -46,7 +46,7 @@ $_: "c-acceptance";
     }
 
     .#{$_}__modal-title {
-        --inherit-font-size: var(--font-size-400);
+        --inherit-font-size: tokens.get($_, "font-size-400");
     }
 
     /* Map */

source/components/acceptance/style.scss

@@ -149,7 +149,7 @@ $_: "c-accordion";
 
 .c-accordion__button .c-accordion__button-column,
 .c-accordion__button .c-accordion__button-wrapper {
-    --inherit-font-size: var(--font-size-200);
+    --inherit-font-size: tokens.get($_, "font-size-200");
     --inherit-margin-top: 0;
     --inherit-margin-bottom: 0;
 }

source/components/accordion/style.scss

@@ -31,7 +31,7 @@ $_: "c-block";
     text-decoration: none;
 
     .#{$_}__heading {
-        --inherit-font-size: var(--font-size-400);
+        --inherit-font-size: tokens.get($_, "font-size-400");
     }
 
     .#{$_}__image {

source/components/block/style.scss

@@ -25,7 +25,7 @@ $_: "c-box";
     transition: all 200ms ease-in;
 
     .#{$_}__heading {
-        --inherit-font-size: var(--font-size-400);
+        --inherit-font-size: tokens.get($_, "font-size-400");
     }
 
     .#{$_}__body {

source/components/box/style.scss

@@ -68,7 +68,7 @@ $_: "c-card";
 
     /** Tell child components to inherit font-size from card for better typography scaling */
     .#{$_}__heading {
-        --inherit-font-size: var(--font-size-300);
+        --inherit-font-size: tokens.get($_, "font-size-300");
     }
 
     .#{$_}__header {