19384258487

Committed 15 Nov 2025 04:07AM UTC coverage: 19.747% (+2.5%) from 17.283%

Build # 19384258487

Build Type

push

github

Committed by

k0d3r1s

Commit Message

prettier

Run Details

16 of 30 new or added lines in 4 files covered. (53.33%)

516 existing lines in 7 files now uncovered.

484 of 2451 relevant lines covered (19.75%)

1.03 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

2.8

/Service/HotReloadService.php

<?php declare(strict_types = 1);

/*
 * This file is part of the Valksor package.
 *
 * (c) Davis Zalitis (k0d3r1s)
 * (c) SIA Valksor <packages@valksor.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

namespace ValksorDev\Build\Service;

use Exception;
use JsonException;
use ReflectionClass;
use RuntimeException;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\DependencyInjection\ParameterBag\ParameterBagInterface;
use Valksor\Component\Sse\Service\AbstractService;

use function array_key_exists;
use function array_keys;
use function array_merge;
use function closedir;
use function count;
use function extension_loaded;
use function file_put_contents;
use function is_dir;
use function is_writable;
use function json_encode;
use function ltrim;
use function max;
use function microtime;
use function opendir;
use function pathinfo;
use function preg_match;
use function preg_quote;
use function readdir;
use function sprintf;
use function str_ends_with;
use function str_replace;
use function str_starts_with;
use function stream_select;
use function strtolower;
use function usleep;

use const DIRECTORY_SEPARATOR;
use const PATHINFO_EXTENSION;

/**
 * Hot reload service for automatically triggering browser refreshes when files change.
 *
 * This service monitors file system changes and sends reload signals to connected browsers
 * via Server-Sent Events (SSE). It handles:
 * - File system monitoring with inotify
 * - Intelligent debouncing to prevent excessive reloads
 * - File transformation patterns (e.g., .tailwind.css → .css)
 * - Rate limiting and duplicate change detection
 * - Multi-app project structure support
 */
final class HotReloadService extends AbstractService
{
    /**
     * Deadline for when debounced changes should be flushed.
     * This prevents excessive reloads when multiple files change rapidly.
     */
    private float $debounceDeadline = 0.0;

    /**
     * File transformation patterns for mapping source files to output files.
     * Example: '*.tailwind.css' → ['output_pattern' => '{path}/{name}.css', 'debounce_delay' => 0.5].
     *
     * @var array<string,array<string,mixed>>
     */
    private array $fileTransformations = [];

    /**
     * Path filter for ignoring directories and files during file watching.
     */
    private PathFilter $filter;

    /**
     * Registry of known output files that should trigger reloads.
     * These are the target files generated by transformations (e.g., .css files).
     *
     * @var array<string,bool>
     */
    private array $outputFiles = [];

    /**
     * Pending file changes waiting to be debounced and flushed.
     * Prevents duplicate changes and implements debouncing logic.
     *
     * @var array<string,bool>
     */
    private array $pendingChanges = [];

    public function __construct(
        ParameterBagInterface $bag,
    ) {
        parent::__construct($bag);
        $this->filter = PathFilter::createDefault($this->projectDir);
    }

    public function reload(): void
    {
        // Hot reload service doesn't support manual reload
        $this->io->note('Hot reload service reload requested (no action needed)');
    }

    /**
     * @param array<string,mixed> $config Configuration from hot_reload config section
     */
    public function start(
        array $config = [],
    ): int {
        // SSE server communication now handled via direct service calls

        // Get hot reload configuration from service-based structure
        $hotReloadConfig = $this->parameterBag->get('valksor.build.services.hot_reload.options');

        // Create custom path filter with user exclusions
        $excludePatterns = $hotReloadConfig['exclude'] ?? [];
        $this->filter = $this->createPathFilterWithExclusions($excludePatterns);

        // Validate configuration early to fail fast if setup is incorrect
        if (!$this->validateConfiguration($hotReloadConfig)) {
            return 1; // Return error code for invalid config
        }

        $watchDirs = $hotReloadConfig['watch_dirs'] ?? [];

        // Early return if no watch directories configured - nothing to monitor
        if (empty($watchDirs)) {
            $this->io->warning('No watch directories configured. Hot reload disabled.');

            return Command::SUCCESS;
        }

        // Extract configuration with sensible defaults
        $debounceDelay = $hotReloadConfig['debounce_delay'] ?? 0.3;           // Default 300ms debounce
        $extendedExtensions = $hotReloadConfig['extended_extensions'] ?? [];     // File extensions to watch
        $extendedSuffixes = $hotReloadConfig['extended_suffixes'] ?? ['.tailwind.css' => 0.5]; // Specific file suffixes
        $fileTransformations = $hotReloadConfig['file_transformations'] ?? [
            // Default transformation: Tailwind source files to CSS output
            '*.tailwind.css' => [
                'output_pattern' => '{path}/{name}.css',    // Convert .tailwind.css to .css
                'debounce_delay' => 0.5,                   // Longer debounce for compiled files
                'track_output' => true,                    // Monitor the output CSS file
            ],
        ];

        $this->fileTransformations = $fileTransformations;
        // Lazy load output files only when needed, not during startup
        $this->outputFiles = [];

        try {
            $watcher = new RecursiveInotifyWatcher($this->filter, function (string $path) use ($extendedSuffixes, $debounceDelay, $extendedExtensions): void {
                $this->handleFilesystemChange($path, $extendedSuffixes, $extendedExtensions, $debounceDelay);
            });

            $this->io->text('File watcher initialized successfully');
        } catch (RuntimeException $e) {
            $this->io->error(sprintf('Failed to initialize file watcher: %s', $e->getMessage()));
            $this->io->warning('Hot reload will continue without file watching (manual reload only)');

            // Continue without watcher - will fall back to manual mode
            $watcher = null;
        } catch (Exception $e) {
            $this->io->error(sprintf('Unexpected error initializing watcher: %s', $e->getMessage()));

            // Continue without watcher
            $watcher = null;
        }

        $watchTargets = $this->collectWatchTargets($this->parameterBag->get('kernel.project_dir'), $watchDirs);

        if ([] === $watchTargets) {
            $this->io->warning('No watch targets found. Hot reload will remain idle.');
        } else {
            foreach ($watchTargets as $target) {
                $watcher->addRoot($target);
            }

            $this->io->note(sprintf('Watching %d directories for changes', count($watchTargets)));
        }

        $this->running = true;

        $this->io->success('Hot reload service started');
        $this->io->text(sprintf('[RESOURCE] Watching %d directories | Memory: %.2f MB', count($watchTargets), memory_get_usage(true) / 1024 / 1024));

        while ($this->running) {
            if ($watcher) {
                $read = [$watcher->getStream()];
                $write = null;
                $except = null;

                // Calculate dynamic timeout based on debouncing needs
                $timeout = $this->calculateSelectTimeout();
                $seconds = $timeout >= 1 ? (int) $timeout : 0;
                $microseconds = $timeout >= 1 ? (int) (($timeout - $seconds) * 1_000_000) : (int) max($timeout * 1_000_000, 50_000);
                // Minimum 50ms timeout to prevent busy waiting, maximum based on debounce deadline

                // Add error handling around stream_select
                try {
                    $ready = @stream_select($read, $write, $except, $seconds, $microseconds);

                    if (false === $ready) {
                        // stream_select failed, likely due to signal interruption
                        $this->io->text('Stream select interrupted, continuing...');
                        usleep(100000); // Wait 100ms before retry

                        continue;
                    }

                    if (!empty($read)) {
                        $watcher->poll();
                    }

                    $this->flushPendingReloads();
                } catch (Exception $e) {
                    $this->io->error(sprintf('Error in file watching loop: %s', $e->getMessage()));
                    // Continue running but log the error
                }
            } else {
                // No watcher available, just wait with timeout
                usleep(100000); // 100ms
            }
        }

        return 0;
    }

    public function stop(): void
    {
        $this->running = false;
    }

    public static function getServiceName(): string
    {
        return 'hot-reload';
    }

    private function calculateSelectTimeout(): float
    {
        $now = microtime(true);

        if ($this->debounceDeadline > 0) {
            return max(0.05, $this->debounceDeadline - $now);
        }

        return 1.0;
    }

    /**
     * Categorize an exclude pattern into the appropriate filter type.
     */
    private function categorizeExcludePattern(
        string $pattern,
        array &$dirs,
        array &$globs,
        array &$filenames,
        array &$extensions,
    ): void {
        // Glob patterns (contain wildcards)
        if (str_contains($pattern, '*') || str_contains($pattern, '?')) {
            $globs[] = $pattern;

            return;
        }

        // File extensions (start with dot)
        if (str_starts_with($pattern, '.')) {
            $extensions[] = $pattern;

            return;
        }

        // Path patterns (contain path separators)
        if (str_contains($pattern, '/')) {
            $globs[] = $pattern;

            return;
        }

        // Simple directory names (no slashes, no wildcards)
        if (!str_contains($pattern, '.')) {
            $dirs[] = $pattern;

            return;
        }

        // Everything else treat as glob pattern
        $globs[] = $pattern;
    }

    /**
     * @return array<int,string>
     */
    private function collectWatchTargets(
        string $projectRoot,
        array $watchDirs,
    ): array {
        $targets = [];

        foreach ($watchDirs as $dir) {
            $fullPath = $projectRoot . DIRECTORY_SEPARATOR . ltrim($dir, '/');

            if (is_dir($fullPath) && !$this->shouldExcludeDirectory($fullPath)) {
                $targets[] = $fullPath;
            }
        }

        return $targets;
    }

    /**
     * Create a PathFilter that merges default exclusions with custom exclude patterns.
     */
    private function createPathFilterWithExclusions(
        array $excludePatterns = [],
    ): PathFilter {
        if (empty($excludePatterns)) {
            return PathFilter::createDefault($this->projectDir);
        }

        // Get default filter values
        $defaultFilter = PathFilter::createDefault($this->projectDir);

        // Start with default exclusions using reflection to access private properties
        $defaultExclusions = $this->extractDefaultExclusions($defaultFilter);

        // Categorize custom patterns
        $customDirs = [];
        $customGlobs = [];
        $customFilenames = [];
        $customExtensions = [];

        foreach ($excludePatterns as $pattern) {
            $this->categorizeExcludePattern($pattern, $customDirs, $customGlobs, $customFilenames, $customExtensions);
        }

        // Merge with defaults
        $mergedDirs = array_merge($defaultExclusions['directories'], $customDirs);
        $mergedGlobs = array_merge($defaultExclusions['globs'], $customGlobs);
        $mergedFilenames = array_merge($defaultExclusions['filenames'], $customFilenames);
        $mergedExtensions = array_merge($defaultExclusions['extensions'], $customExtensions);

        return new PathFilter($mergedDirs, $mergedGlobs, $mergedFilenames, $mergedExtensions, $this->projectDir);
    }

    private function determineReloadDelay(
        string $path,
        array $extendedExtensions,
        array $extendedSuffixes,
        float $debounceDelay,
    ): float {
        // Priority 1: Check if this is a source file that matches transformation patterns
        // Source files get their configured debounce delay (typically longer for compiled files)
        foreach ($this->fileTransformations as $pattern => $config) {
            if ($this->matchesPattern($path, $pattern)) {
                return $config['debounce_delay'] ?? $debounceDelay;
            }
        }

        // Priority 2: Check extended suffixes (legacy support for specific file patterns)
        // Provides backward compatibility with older configuration formats
        foreach ($extendedSuffixes as $suffix => $delay) {
            if (str_ends_with($path, $suffix)) {
                return $delay;
            }
        }

        // Priority 3: Check file extensions for general file type handling
        $extension = strtolower(pathinfo($path, PATHINFO_EXTENSION));

        if ('' !== $extension && array_key_exists($extension, $extendedExtensions)) {
            return $extendedExtensions[$extension];
        }

        // Priority 4: Use default debounce delay for all other files
        return $debounceDelay;
    }

    /**
     * @param array<string,array<string,mixed>> $transformations
     *
     * @return array<string,bool>
     */
    private function discoverOutputFiles(
        string $projectRoot,
        array $transformations,
    ): array {
        $outputs = [];

        foreach ($transformations as $pattern => $config) {
            if (!($config['track_output'] ?? true)) {
                continue;
            }

            $roots = $config['watch_dirs'] ?? [
                $projectRoot . $this->parameterBag->get('valksor.project.apps_dir'),
                $projectRoot . $this->parameterBag->get('valksor.project.infrastructure_dir'),
            ];

            foreach ($roots as $root) {
                $root = $projectRoot . DIRECTORY_SEPARATOR . ltrim($root, '/');

                if (!is_dir($root)) {
                    continue;
                }

                $this->visitSources($root, $pattern, $config['output_pattern'], $outputs);
            }
        }

        return $outputs;
    }

    /**
     * Extract default exclusions from PathFilter using reflection.
     */
    private function extractDefaultExclusions(
        PathFilter $filter,
    ): array {
        $reflection = new ReflectionClass($filter);

        $directories = $reflection->getProperty('ignoredDirectories')->getValue($filter);
        $globs = $reflection->getProperty('ignoredGlobs')->getValue($filter);
        $filenames = $reflection->getProperty('ignoredFilenames')->getValue($filter);
        $extensions = $reflection->getProperty('ignoredExtensions')->getValue($filter);

        return [
            'directories' => $directories,
            'globs' => $globs,
            'filenames' => $filenames,
            'extensions' => $extensions,
        ];
    }

    /**
     * @throws JsonException
     */
    private function flushPendingReloads(): void
    {
        if ([] === $this->pendingChanges || microtime(true) < $this->debounceDeadline) {
            return;
        }

        $files = array_keys($this->pendingChanges);
        $this->pendingChanges = [];
        $this->debounceDeadline = 0.0;

        // Write signal file for SSE service with error handling
        $signalFile = $this->parameterBag->get('kernel.project_dir') . '/var/run/valksor-reload.signal';
        $signalData = json_encode(['files' => $files, 'timestamp' => microtime(true)], JSON_THROW_ON_ERROR);

        try {
            $result = file_put_contents($signalFile, $signalData);

            if (false === $result) {
                throw new RuntimeException('Failed to write signal file');
            }
        } catch (Exception $e) {
            $this->io->error(sprintf('Failed to write reload signal: %s', $e->getMessage()));

            return;
        }

        $this->io->success(sprintf('Reload signal sent for %d changed files', count($files)));

        // Refresh file list after sending signal to handle new/deleted files
        $this->refreshWatchTargets();
    }

    /**
     * Generate output file path from pattern.
     */
    private function generateOutputPath(
        string $projectRoot,
        string $relativeDir,
        string $filename,
        string $outputPattern,
    ): string {
        $placeholders = [
            '{path}' => $relativeDir,
            '{name}' => $filename,
        ];

        $outputPath = $outputPattern;

        foreach ($placeholders as $placeholder => $value) {
            $outputPath = str_replace($placeholder, $value, $outputPath);
        }

        return $projectRoot . DIRECTORY_SEPARATOR . $outputPath;
    }

    private function handleFilesystemChange(
        string $path,
        array $extendedSuffixes,
        array $extendedExtensions,
        float $debounceDelay,
    ): void {
        // Ignore files that match the path filter (e.g., .git, node_modules, vendor)
        if ($this->filter->shouldIgnorePath($path)) {
            return;
        }

        // Lazy load output files discovery to avoid expensive directory scanning during startup
        if (empty($this->outputFiles)) {
            $this->outputFiles = $this->discoverOutputFiles($this->parameterBag->get('kernel.project_dir'), $this->fileTransformations);
        }

        $now = microtime(true);

        // Determine the appropriate debounce delay for this specific file type
        $fileDelay = $this->determineReloadDelay($path, $extendedExtensions, $extendedSuffixes, $debounceDelay);

        // Calculate when this change should be flushed (debounce deadline)
        // Always reset the deadline - this is the key to proper debouncing behavior
        $this->debounceDeadline = $now + $fileDelay;

        // Add this file to the pending changes queue
        $this->pendingChanges[$path] = true;

        $this->io->text(sprintf('File changed: %s', $path));
    }

    /**
     * Check if a file path matches a glob pattern.
     *
     * Converts simple glob patterns (like *.tailwind.css) to regex for matching
     * against absolute file paths. This supports the transformation pattern system.
     *
     * Examples:
     * - "*.tailwind.css" matches all .tailwind.css files in any directory
     *
     * @param string $path    Absolute file path to check
     * @param string $pattern Glob pattern to match against
     *
     * @return bool True if the path matches the pattern
     */
    private function matchesPattern(
        string $path,
        string $pattern,
    ): bool {
        // Convert glob pattern to regex pattern
        // * becomes .* (match any characters)
        // ? becomes . (match any single character)
        $pattern = str_replace(['*', '?'], ['.*', '.'], $pattern);

        // Create full regex pattern that matches from project root
        $pattern = '#^' . preg_quote($this->parameterBag->get('kernel.project_dir') . DIRECTORY_SEPARATOR, '#') . $pattern . '$#';

        return 1 === preg_match($pattern, $path);
    }

    /**
     * Refresh watch targets and output files after a reload cycle.
     * This ensures new and deleted files are properly tracked.
     */
    private function refreshWatchTargets(): void
    {
        // Clear existing output files and rediscover
        $this->outputFiles = $this->discoverOutputFiles($this->parameterBag->get('kernel.project_dir'), $this->fileTransformations);

        $this->io->text(sprintf('Refreshed file discovery - tracking %d output files', count($this->outputFiles)));
    }

    /**
     * Check if a directory should be excluded based on exclude patterns.
     */
    private function shouldExcludeDirectory(
        string $dirPath,
    ): bool {
        // Get relative path from project root for pattern matching
        $projectRoot = $this->parameterBag->get('kernel.project_dir');
        $relativePath = str_replace($projectRoot . DIRECTORY_SEPARATOR, '', $dirPath);

        // Use PathFilter to check if this directory should be excluded
        return $this->filter->shouldIgnoreDirectory($relativePath) || $this->filter->shouldIgnorePath($relativePath);
    }

    /**
     * Validate hot reload configuration before starting.
     */
    private function validateConfiguration(
        array $config,
    ): bool {
        $projectRoot = $this->parameterBag->get('kernel.project_dir');

        // Validate var/run directory exists and is writable
        $runDir = $projectRoot . '/var/run';
        $this->ensureDirectory($runDir);

        if (!is_writable($runDir)) {
            $this->io->error(sprintf('Run directory is not writable: %s', $runDir));

            return false;
        }

        // Validate watch directories exist
        foreach ($config['watch_dirs'] ?? [] as $dir) {
            $fullPath = $projectRoot . '/' . ltrim($dir, '/');

            if (!is_dir($fullPath)) {
                $this->io->warning(sprintf('Watch directory does not exist: %s', $fullPath));
            }
        }

        // Check if inotify extension is available
        if (!extension_loaded('inotify')) {
            $this->io->warning('PHP inotify extension is not available. File watching may not work optimally.');
        }

        return true;
    }

    /**
     * @param array<string,bool> $outputs
     */
    private function visitSources(
        string $path,
        string $pattern,
        string $outputPattern,
        array &$outputs,
    ): void {
        $handle = opendir($path);

        if (false === $handle) {
            return;
        }

        try {
            while (($entry = readdir($handle)) !== false) {
                if ('.' === $entry || '..' === $entry) {
                    continue;
                }

                $full = $path . DIRECTORY_SEPARATOR . $entry;

                if (is_dir($full)) {
                    if ($this->filter->shouldIgnoreDirectory($entry)) {
                        continue;
                    }
                    $this->visitSources($full, $pattern, $outputPattern, $outputs);

                    continue;
                }

                if (!$this->matchesPattern($full, $pattern)) {
                    continue;
                }

                // Generate output file path
                $relativePath = str_replace($this->parameterBag->get('kernel.project_dir') . DIRECTORY_SEPARATOR, '', $full);
                $pathInfo = pathinfo($relativePath);

                $outputFile = $this->generateOutputPath(
                    $this->parameterBag->get('kernel.project_dir'),
                    $pathInfo['dirname'] ?? '',
                    $pathInfo['filename'],
                    $outputPattern,
                );

                $outputs[$outputFile] = true;
            }
        } finally {
            closedir($handle);
        }
    }
}

valksor / php-dev-build / 19384258487

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous