WP-LIT-MCP/tests/Unit/Guides/ToolNamingTest.php

<?php

declare(strict_types=1);

namespace LIT\MCP\Tests\Unit\Guides;

use LIT\MCP\Abilities\Ability;
use LIT\MCP\Tests\Unit\TestCase;
use RecursiveDirectoryIterator;
use RecursiveIteratorIterator;
use ReflectionClass;

/**
 * Guides, descriptions and hints must name tools the way the client sees them: direct
 * tools as lit-<name>, indirect ones as lit/<name> (reached via mcp-adapter-execute-ability),
 * and error codes without the internal lit_ prefix of the WP_Error code.
 */
final class ToolNamingTest extends TestCase
{
    /** @return array<string, bool> Ability name without "lit/" => isDirect(). */
    private static function abilities(): array
    {
        $root = dirname(__DIR__, 3);
        $abilities = [];
        $files = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($root . '/src'));
        foreach ($files as $file) {
            if (! str_ends_with((string) $file, 'Ability.php')) {
                continue;
            }

            $class = 'LIT\\MCP\\' . str_replace(['/', '.php'], ['\\', ''], substr((string) $file, strlen($root . '/src/')));
            $reflection = new ReflectionClass($class);
            if (! $reflection->isInstantiable() || ! $reflection->implementsInterface(Ability::class)) {
                continue;
            }

            /** @var Ability $ability */
            $ability = $reflection->newInstanceWithoutConstructor();
            $abilities[substr($ability->name(), strlen('lit/'))] = $ability->isDirect();
        }

        ksort($abilities);

        return $abilities;
    }

    /** @return array<string, string> Path => content of the guides and all PHP sources. */
    private static function texts(): array
    {
        $root = dirname(__DIR__, 3);
        $texts = [];
        foreach (glob($root . '/docs/guides/*.md') ?: [] as $file) {
            $texts[$file] = (string) file_get_contents($file);
        }

        $files = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($root . '/src'));
        foreach ($files as $file) {
            if (str_ends_with((string) $file, '.php')) {
                $texts[(string) $file] = (string) file_get_contents((string) $file);
            }
        }

        return $texts;
    }

    public function testIndirectToolsAreNeverNamedLikeDirectOnes(): void
    {
        $abilities = self::abilities();
        self::assertArrayHasKey('menu-set-items', $abilities);

        foreach (self::texts() as $path => $text) {
            preg_match_all('/\blit-([a-z]+(?:-[a-z]+)*)/', $text, $matches);
            foreach ($matches[1] as $name) {
                self::assertFalse(
                    ($abilities[$name] ?? true) === false,
                    sprintf('%s names the indirect tool lit/%s as lit-%s', basename($path), $name, $name)
                );
            }

            preg_match_all('#\blit/([a-z]+(?:-[a-z]+)*)#', $text, $matches);
            foreach ($matches[1] as $name) {
                self::assertFalse(
                    ($abilities[$name] ?? false) === true && str_ends_with($path, '.md'),
                    sprintf('%s names the direct tool lit-%s as lit/%s', basename($path), $name, $name)
                );
            }
        }
    }

    public function testGuidesUseTheErrorCodesTheClientSees(): void
    {
        foreach (self::texts() as $path => $text) {
            if (str_ends_with($path, '.md')) {
                self::assertDoesNotMatchRegularExpression('/`lit_(?!mcp)[a-z_]+`/', $text, basename($path));
            }
        }
    }

    /** Every guide topic named in a description, hint or the overview exists as docs/guides/<topic>.md. */
    public function testReferencedGuideTopicsExist(): void
    {
        $root = dirname(__DIR__, 3);
        $referenced = [];
        foreach (self::texts() as $path => $text) {
            if (str_ends_with($path, '.php')) {
                preg_match_all('/topic \\\\?"([a-z0-9-]+)\\\\?"/', $text, $matches);
                $referenced = array_merge($referenced, $matches[1]);
            }
        }

        self::assertContains('divi-shortform', $referenced, 'lit/divi-insert and lit/content-create name divi-shortform');
        foreach (array_unique($referenced) as $topic) {
            self::assertFileExists($root . '/docs/guides/' . $topic . '.md', 'guide topic "' . $topic . '"');
        }
    }

    public function testOverviewListsExactlyTheOtherGuideTopics(): void
    {
        $root = dirname(__DIR__, 3);
        $overview = (string) file_get_contents($root . '/docs/guides/overview.md');
        preg_match('/Weitere Themen:(.*?)\n\n/s', $overview, $section);
        preg_match_all('/`([a-z0-9-]+)`/', $section[1] ?? '', $listed);
        $listedTopics = array_values(array_diff($listed[1], ['topic', 'lit-guide']));
        sort($listedTopics);

        $files = array_map(static fn (string $f): string => basename($f, '.md'), glob($root . '/docs/guides/*.md') ?: []);
        $files = array_values(array_diff($files, ['overview']));
        sort($files);

        self::assertSame($files, $listedTopics);
    }

    /** Every indirect tool is named in the overview (the only place a client learns which `lit/` tools exist). */
    public function testOverviewNamesEveryIndirectTool(): void
    {
        $overview = (string) file_get_contents(dirname(__DIR__, 3) . '/docs/guides/overview.md');
        preg_match_all('#`lit/([a-z]+(?:-[a-z]+)*)`#', $overview, $named);

        $indirect = array_keys(array_filter(self::abilities(), static fn (bool $direct): bool => ! $direct));
        self::assertNotEmpty($indirect);
        self::assertSame([], array_values(array_diff($indirect, $named[1])), 'indirect tools missing in overview.md');
    }

    public function testOverviewListsExactlyTheDirectTools(): void
    {
        $overview = (string) file_get_contents(dirname(__DIR__, 3) . '/docs/guides/overview.md');
        preg_match('/Direkt sichtbar:(.*?)\n\n/s', $overview, $section);
        preg_match_all('/`lit-([a-z-]+)`/', $section[1] ?? '', $listed);

        $direct = array_keys(array_filter(self::abilities()));
        $listedNames = $listed[1];
        sort($listedNames);

        self::assertSame($direct, $listedNames);
    }
}