ModuleScanner.php

<?php

declare(strict_types=1);

namespace OpenForgeProject\MageForge\Service\Hyva;

use Magento\Framework\Filesystem\Driver\File;

/**
 * Service that scans module directories for files containing Hyvä compatibility issues
 *
 * Recursively scans JavaScript, XML, and PHTML files within module directories
 * to identify patterns that may be incompatible with Hyvä themes.
 *
 * @phpstan-import-type ScanIssue from IncompatibilityDetector
 * @phpstan-type ScanResult array{files: array<string, array<int, ScanIssue>>, totalIssues: int, criticalIssues: int}
 * @phpstan-type ModuleInfo array{name: string, version: string, isHyvaAware: bool}
 */
class ModuleScanner
{
    private const SCAN_EXTENSIONS = ['js', 'xml', 'phtml', 'html'];
    private const EXCLUDE_DIRECTORIES = ['Test', 'tests', 'node_modules', 'vendor'];

    /**
     * @param File $fileDriver
     * @param IncompatibilityDetector $incompatibilityDetector
     */
    public function __construct(
        private readonly File $fileDriver,
        private readonly IncompatibilityDetector $incompatibilityDetector,
    ) {
    }

    /**
     * Scan a module directory for compatibility issues
     *
     * @param string $modulePath
     * @return array<string, mixed> Array with structure: ['files' => [], 'totalIssues' => int, 'criticalIssues' => int]
     * @phpstan-return ScanResult
     */
    public function scanModule(string $modulePath): array
    {
        if (!$this->fileDriver->isDirectory($modulePath)) {
            return ['files' => [], 'totalIssues' => 0, 'criticalIssues' => 0];
        }

        $filesWithIssues = [];
        $totalIssues = 0;
        $criticalIssues = 0;

        $files = $this->findRelevantFiles($modulePath);

        foreach ($files as $file) {
            $issues = $this->incompatibilityDetector->detectInFile($file);

            if (!empty($issues)) {
                $relativePath = str_replace($modulePath . '/', '', $file);
                $filesWithIssues[$relativePath] = $issues;
                $totalIssues += count($issues);

                foreach ($issues as $issue) {
                    if ($issue['severity'] === 'critical') {
                        $criticalIssues++;
                    }
                }
            }
        }

        return [
            'files' => $filesWithIssues,
            'totalIssues' => $totalIssues,
            'criticalIssues' => $criticalIssues,
        ];
    }

    /**
     * Recursively find all relevant files in a directory
     *
     * @param string $directory
     * @return array<int, string>
     */
    private function findRelevantFiles(string $directory): array
    {
        $relevantFiles = [];

        try {
            $items = $this->fileDriver->readDirectory($directory);

            foreach ($items as $item) {
                $basename = $this->getBasename($item);

                // Skip excluded directories
                if ($this->fileDriver->isDirectory($item)) {
                    if (in_array($basename, self::EXCLUDE_DIRECTORIES, true)) {
                        continue;
                    }
                    // Recursively scan subdirectories
                    foreach ($this->findRelevantFiles($item) as $childFile) {
                        $relevantFiles[] = $childFile;
                    }
                    continue;
                }

                // Check if file has relevant extension
                $extension = $this->incompatibilityDetector->getExtensionFromPath($item);
                if (in_array($extension, self::SCAN_EXTENSIONS, true)) {
                    $relevantFiles[] = $item;
                }
            }
        } catch (\Throwable $e) {
            // Skip directories that can't be read
            return $relevantFiles;
        }

        return $relevantFiles;
    }

    /**
     * Check if module has Hyvä compatibility package based on composer data
     *
     * @param array $composerData Parsed composer.json data
     * @phpstan-param array<string, mixed> $composerData
     */
    private function isHyvaCompatibilityPackage(array $composerData): bool
    {
        // Check if this IS a Hyvä compatibility package
        $packageName = $composerData['name'] ?? '';
        $isCompatPackage =
            is_string($packageName)
            && str_starts_with($packageName, 'hyva-themes/')
            && str_contains($packageName, '-compat');
        if ($isCompatPackage) {
            return true;
        }

        // Check dependencies for Hyvä packages
        $requires = $composerData['require'] ?? [];
        if (!is_array($requires)) {
            return false;
        }
        foreach ($requires as $package => $version) {
            if (is_string($package) && str_starts_with($package, 'hyva-themes/')) {
                return true;
            }
        }

        return false;
    }

    /**
     * Get module info from composer.json
     *
     * @param string $modulePath
     * @return array<string, mixed>
     * @phpstan-return ModuleInfo
     */
    public function getModuleInfo(string $modulePath): array
    {
        $composerPath = $modulePath . '/composer.json';

        if (!$this->fileDriver->isExists($composerPath)) {
            return ['name' => 'Unknown', 'version' => 'Unknown', 'isHyvaAware' => false];
        }

        try {
            $content = $this->fileDriver->fileGetContents($composerPath);
            $composerData = json_decode($content, true);

            if (!is_array($composerData)) {
                return ['name' => 'Unknown', 'version' => 'Unknown', 'isHyvaAware' => false];
            }

            /** @var array<string, mixed> $composerData */
            return [
                'name' => is_string($composerData['name'] ?? null) ? $composerData['name'] : 'Unknown',
                'version' => is_string($composerData['version'] ?? null) ? $composerData['version'] : 'Unknown',
                'isHyvaAware' => $this->isHyvaAware($modulePath, $composerData),
            ];
        } catch (\Throwable $e) {
            return ['name' => 'Unknown', 'version' => 'Unknown', 'isHyvaAware' => false];
        }
    }

    /**
     * Determine whether a module is Hyvä-aware.
     *
     * A module is considered Hyvä-aware when it either declares a Hyvä dependency,
     * is a Hyvä compatibility package, or ships a hyva-themes.json config.
     *
     * @param string $modulePath
     * @param array $composerData
     * @phpstan-param array<string, mixed> $composerData
     * @return bool
     */
    private function isHyvaAware(string $modulePath, array $composerData): bool
    {
        if ($this->isHyvaCompatibilityPackage($composerData)) {
            return true;
        }

        return $this->fileDriver->isExists($modulePath . '/hyva-themes.json');
    }

    /**
     * Get basename without using basename().
     *
     * @param string $path
     * @return string
     */
    private function getBasename(string $path): string
    {
        $normalized = str_replace('\\', '/', $path);
        $trimmed = rtrim($normalized, '/');
        $pos = strrpos($trimmed, '/');
        if ($pos === false) {
            return $trimmed;
        }
        return substr($trimmed, $pos + 1);
    }
}