feat(router): support dead link detection when generating static pages

Author: innocenzi

packages/router/src/Static/Exceptions/DeadLinksDetectedException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Tempest\Router\Static\Exceptions;
+
+final class DeadLinksDetectedException extends StaticPageException
+{
+    public function __construct(
+        string $uri,
+        public readonly array $links,
+    ) {
+        parent::__construct(sprintf('%s has %s dead links', $uri, count($links)), $uri);
+    }
+}

packages/router/src/Static/StaticGenerateCommand.php

@@ -10,48 +10,61 @@
 use Tempest\Console\ExitCode;
 use Tempest\Console\HasConsole;
 use Tempest\Container\Container;
+use Tempest\Core\AppConfig;
 use Tempest\Core\Kernel;
 use Tempest\EventBus\EventBus;
 use Tempest\Http\GenericRequest;
 use Tempest\Http\Method;
 use Tempest\Http\Status;
+use Tempest\HttpClient\HttpClient;
 use Tempest\Router\DataProvider;
 use Tempest\Router\Router;
+use Tempest\Router\Static\Exceptions\DeadLinksDetectedException;
 use Tempest\Router\Static\Exceptions\InvalidStatusCodeException;
 use Tempest\Router\Static\Exceptions\NoTextualBodyException;
+use Tempest\Support\Regex;
+use Tempest\Support\Str;
 use Tempest\View\Exceptions\ViewCompilationError;
 use Tempest\View\View;
 use Tempest\View\ViewRenderer;
 use Tempest\Vite\Exceptions\ManifestNotFoundException;
 use Throwable;
 
+use function Tempest\Support\Language\pluralize;
 use function Tempest\Support\path;
 use function Tempest\uri;
 
-final readonly class StaticGenerateCommand
+final class StaticGenerateCommand
 {
     use HasConsole;
 
+    private array $verifiedLinks = [];
+
     public function __construct(
-        private Console $console,
-        private Kernel $kernel,
-        private Container $container,
-        private StaticPageConfig $staticPageConfig,
-        private Router $router,
-        private ViewRenderer $viewRenderer,
-        private EventBus $eventBus,
+        private readonly AppConfig $appConfig,
+        private readonly Console $console,
+        private readonly Kernel $kernel,
+        private readonly Container $container,
+        private readonly StaticPageConfig $staticPageConfig,
+        private readonly Router $router,
+        private readonly ViewRenderer $viewRenderer,
+        private readonly EventBus $eventBus,
+        private readonly HttpClient $httpClient,
     ) {}
 
     #[ConsoleCommand(name: 'static:generate', description: 'Compiles static pages')]
     public function __invoke(
         ?string $filter = null,
+        bool $allowDeadLinks = false,
+        bool $allowExternalDeadLinks = true,
         #[ConsoleArgument(aliases: ['v'])]
         bool $verbose = false,
     ): ExitCode {
         $publicPath = path($this->kernel->root, 'public');
 
         $generated = 0;
         $failures = 0;
+        $deadlinks = [];
 
         $this->console->header('Generating static pages');
 
@@ -64,6 +77,10 @@ public function __invoke(
             $failures++;
 
             match (true) {
+                $event->exception instanceof DeadLinksDetectedException => $this->keyValue(
+                    "<style='fg-gray'>{$event->path}</style>",
+                    sprintf("<style='fg-red'>%s DEAD %s</style>", count($event->exception->links), pluralize('LINK', count($event->exception->links))),
+                ),
                 $event->exception instanceof InvalidStatusCodeException => $this->keyValue(
                     "<style='fg-gray'>{$event->path}</style>",
                     "<style='fg-red'>HTTP {$event->exception->status->value}</style>",
@@ -126,6 +143,11 @@ public function __invoke(
                         mkdir($directory->toString(), recursive: true);
                     }
 
+                    if (! $allowDeadLinks && count($links = $this->detectDeadLinks($uri, $content, checkExternal: ! $allowExternalDeadLinks)) > 0) {
+                        $deadlinks[$uri] = $links;
+                        throw new DeadLinksDetectedException($uri, $links);
+                    }
+
                     file_put_contents($file->toString(), $content);
 
                     $this->eventBus->dispatch(new StaticPageGenerated($uri, $file->toString(), $content));
@@ -152,8 +174,119 @@ public function __invoke(
 
         $this->keyValue('Static pages generated', "<style='fg-green'>{$generated}</style>");
 
-        return $failures > 0
+        if ($deadlinks) {
+            $this->console->header('Dead links');
+
+            foreach ($deadlinks as $uri => $links) {
+                foreach ($links as $link) {
+                    $this->keyValue("<style='fg-gray'>{$uri}</style>", "<style='fg-red'>{$link}</style>");
+                }
+            }
+        }
+
+        return $failures > 0 || count($deadlinks) > 0
             ? ExitCode::ERROR
             : ExitCode::SUCCESS;
     }
+
+    private function detectDeadLinks(string $uri, string $html, bool $checkExternal = false): array
+    {
+        $deadlinks = [];
+        $links = Regex\get_all_matches($html, '/<a\s+(?<ignore>ssg-ignore)?[^>]*href=["\'](?<url>[^"\']+)["\'][^>]*>/i', matches: ['url', 'ignore']);
+
+        foreach ($links as ['url' => $link, 'ignore' => $ignore]) {
+            // Links can be ignored with the ssg-ignore attribute
+            if ($ignore ?: false) {
+                continue;
+            }
+
+            // Check anchors (#)
+            if (Str\starts_with($link, '#')) {
+                if (! Regex\matches($html, "/id=\"" . preg_quote(Str\strip_start($link, '#'), '/') . "\"/")) {
+                    $deadlinks[] = $link;
+                }
+
+                continue;
+            }
+
+            // Resolve relative links (../ or ./)
+            if (Str\starts_with($link, ['../', './'])) {
+                $link = $this->resolveRelativeLink($uri, $link);
+            }
+
+            // Don't ping the same link multiple times
+            if (in_array($link, $this->verifiedLinks, strict: true)) {
+                continue;
+            }
+
+            $this->verifiedLinks[] = $link;
+
+            // Check internal links with router (/ or same base uri)
+            if (Str\starts_with($link, '/') || Str\starts_with($this->getLinkWithoutProtocol($link), $this->getLinkWithoutProtocol($this->appConfig->baseUri))) {
+                $response = $this->router->dispatch(new GenericRequest(
+                    method: Method::GET,
+                    uri: match (true) {
+                        Str\starts_with($link, '/') => $this->appConfig->baseUri . '/' . Str\strip_start($link, '/'),
+                        default => $link,
+                    },
+                ));
+
+                if ($response->status->isClientError() || $response->status->isServerError()) {
+                    $deadlinks[] = $link;
+                }
+
+                continue;
+            }
+
+            if (! $checkExternal) {
+                continue;
+            }
+
+            if (Str\starts_with($link, 'http')) {
+                $response = $this->httpClient->get($link);
+
+                if ($response->status->isClientError() || $response->status->isServerError()) {
+                    $deadlinks[] = $link;
+                }
+
+                continue;
+            }
+
+            // If we reach this, there is an unknown kind of link.
+        }
+
+        return $deadlinks;
+    }
+
+    /**
+     * Resolves paths starting with ./ or ../ to a canonical URI.
+     */
+    private function resolveRelativeLink(string $basePath, string $relativePath): string
+    {
+        $basePath = Str\strip_end($basePath, '/');
+
+        if (Str\starts_with($relativePath, ['../', './'])) {
+            $baseParts = explode('/', $basePath);
+            $relativeParts = explode('/', $relativePath);
+
+            array_pop($baseParts);
+
+            foreach ($relativeParts as $part) {
+                if ($part === '..') {
+                    array_pop($baseParts);
+                } elseif ($part !== '.') {
+                    $baseParts[] = $part;
+                }
+            }
+
+            return implode('/', $baseParts);
+        }
+
+        return $basePath . '/' . Str\strip_start($relativePath, './');
+    }
+
+    private function getLinkWithoutProtocol(string $link): string
+    {
+        return Str\strip_start($link, ['https://', 'http://']);
+    }
 }