feat: improve validation

Author: raphaelstolt

CHANGELOG.md

@@ -7,6 +7,11 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 ## [Unreleased]
 
+## [v3.4.0] - 2025-10-14
+
+### Added
+- Improved `LlmsTxt::validation` by providing more information about the validation errors. Closes issue [8](https://github.com/raphaelstolt/llms-txt-php/issues/8).
+
 ## [v3.3.0] - 2025-09-20
 
 ### Added
@@ -123,7 +128,8 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 - Initial release.
 
-[Unreleased]: https://github.com/raphaelstolt/llms-txt-php/compare/v3.3.0...HEAD
+[Unreleased]: https://github.com/raphaelstolt/llms-txt-php/compare/v3.4.0...HEAD
+[v3.4.0]: https://github.com/raphaelstolt/llms-txt-php/compare/v3.3.0...v3.4.0
 [v3.3.0]: https://github.com/raphaelstolt/llms-txt-php/compare/v3.2.0...v3.3.0
 [v3.2.0]: https://github.com/raphaelstolt/llms-txt-php/compare/v3.1.0...v3.2.0
 [v3.1.0]: https://github.com/raphaelstolt/llms-txt-php/compare/v3.0.0...v3.1.0

src/LlmsTxt.php

@@ -6,6 +6,8 @@
 
 use \Exception;
 use Stolt\LlmsTxt\Section\Link;
+use Stolt\LlmsTxt\Validation\ValidationError;
+use Stolt\LlmsTxt\Validation\ValidationResult;
 
 final class LlmsTxt
 {
@@ -112,15 +114,55 @@ public function toString(): string
     }
 
     /**
+     * Validates a given llms.txt file content.
+     *
+     * If `$detailed` is false (default), it returns a simple boolean for backward compatibility.
+     * If `$detailed` is true, returns a `ValidationResult` object with rich diagnostics.
+     *
+     * @param bool $detailed Whether to return a ValidationResult instead of a boolean.
+     *
      * @throws Exception
+     * @return bool|ValidationResult
      */
-    public function validate(): bool
+    public function validate(bool $detailed = false): bool|ValidationResult
     {
         if ($this->hasBeenParsed) {
+
+
             if ($this->title !== '' && $this->description !== '' && $this->details !== '' && \count($this->sections) > 0 && \count($this->sections[0]->getLinks()) > 0) {
+                if ($detailed) {
+                    return new ValidationResult();
+                }
                 return true;
             }
 
+            if ($detailed) {
+                $result = new ValidationResult();
+
+                if (!isset($this->title) || empty($this->title)) {
+                    $result->addError(new ValidationError('Missing title'));
+                }
+
+                if (!isset($this->description) || empty($this->description)) {
+                    $result->addError(new ValidationError('Missing description'));
+                }
+
+                if (!isset($this->details) || empty($this->details)) {
+                    $result->addError(new ValidationError('Missing details'));
+                }
+
+                if (\count($this->sections) === 0) {
+                    $result->addError(new ValidationError('Missing at least one section'));
+                    $result->addError(new ValidationError('Missing at least one section link'));
+                }
+
+                if (\count($this->sections) > 0 && \count($this->sections[0]->getLinks()) === 0) {
+                    $result->addError(new ValidationError('Missing at least one section link'));
+                }
+
+                return $result;
+            }
+
             return false;
         }
 

src/Validation/ValidationError.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Stolt\LlmsTxt\Validation;
+
+final class ValidationError
+{
+    public function __construct(
+        private readonly string $message
+    ) {
+    }
+
+    public function message(): string
+    {
+        return $this->message;
+    }
+}

src/Validation/ValidationResult.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Stolt\LlmsTxt\Validation;
+
+final class ValidationResult
+{
+    /** @var ValidationError[] */
+    private array $errors = [];
+
+    public function addError(ValidationError $error): void
+    {
+        $this->errors[] = $error;
+    }
+
+    public function isValid(): bool
+    {
+        return empty($this->errors);
+    }
+
+    /**
+     * @return ValidationError[]
+     */
+    public function errors(): array
+    {
+        return $this->errors;
+    }
+}

tests/LlmsTxtTest.php

@@ -135,6 +135,27 @@ public function itValidatesLlmsTxtAsExpected(): void
         $this->assertTrue($llmsTxt->validate());
     }
 
+    #[Test]
+    public function itValidatesLlmsTxtWithAValidationResultAsExpected(): void
+    {
+        $llmsTxt = new LlmsTxt();
+        $llmsTxt = $llmsTxt->parse(\realpath(__DIR__ . '/fixtures/uv.llms.md'));
+
+        $validationResult = $llmsTxt->validate(true);
+        $this->assertTrue($validationResult->isValid());
+    }
+
+    #[Test]
+    public function itValidatesLlmsTxtWithAValidationResultAsExpectedWithMissingElements(): void
+    {
+        $llmsTxt = new LlmsTxt();
+        $llmsTxt = $llmsTxt->parse(\realpath(__DIR__ . '/fixtures/invalid.md'));
+
+        $validationResult = $llmsTxt->validate(true);
+        $this->assertFalse($validationResult->isValid());
+        $this->assertCount(4, $validationResult->errors());
+    }
+
     #[Test]
     public function itThrowsExpectedExceptionWhenNotParsedBeforeValidating(): void
     {

tests/fixtures/invalid.md

@@ -0,0 +1 @@
+# Title