- Fix for check timestamp, normalize timestamp comparison

Author: PoloStyle07

src/Commands/GenerateDocsCommand.php

@@ -58,7 +58,7 @@ public function handle(): int
         $content = $generator->generate($groups, $title);
 
         if ($this->option('check')) {
-            return $this->runCheck($content, $resolvedOutput);
+            return $this->runCheck($content, $resolvedOutput, $format);
         }
 
         $this->writeOutput($content, $resolvedOutput);
@@ -115,7 +115,9 @@ private function gatherCommands(): array
                 continue;
             }
 
-            // Only-custom filter (overrides vendor filter)
+            // Only-custom filter: restricts output to application-defined commands only
+            // (matched against app_command_paths). Runs independently of the vendor
+            // filter; application commands are never vendor commands.
             if ($onlyCustom && ! $this->inspector->isApplicationCommand($command, $appPaths)) {
                 continue;
             }
@@ -213,8 +215,13 @@ private function writeOutput(string $content, string $absolutePath): void
     /**
      * Compare generated content against the existing file on disk.
      * Exits with code 1 when the file is missing or differs.
+     *
+     * Timestamps embedded by the generators (Markdown blockquote, JSON
+     * "generated_at" field, HTML meta line) are stripped from both strings
+     * before comparison so that --check does not fail solely because the
+     * documentation was generated at an earlier point in time.
      */
-    private function runCheck(string $content, string $absolutePath): int
+    private function runCheck(string $content, string $absolutePath, string $format): int
     {
         if (! File::exists($absolutePath)) {
             $this->error("❌ Check failed: documentation file does not exist at [{$absolutePath}].");
@@ -225,7 +232,10 @@ private function runCheck(string $content, string $absolutePath): int
 
         $existing = File::get($absolutePath);
 
-        if (trim($existing) === trim($content)) {
+        $normalizedExisting = $this->normalizeForCheck(trim($existing), $format);
+        $normalizedContent = $this->normalizeForCheck(trim($content), $format);
+
+        if ($normalizedExisting === $normalizedContent) {
             $this->info('✅ Documentation is up-to-date.');
 
             return self::SUCCESS;
@@ -236,4 +246,26 @@ private function runCheck(string $content, string $absolutePath): int
 
         return self::FAILURE;
     }
+
+    /**
+     * Strip format-specific timestamp markers from generated content before
+     * performing an equality check.
+     *
+     * Each generator embeds a live timestamp that changes on every run:
+     *   – Markdown : the "Auto-generated on …" blockquote line
+     *   – JSON     : the "generated_at" top-level property
+     *   – HTML     : the "Generated …" suffix inside the <p class="meta"> element
+     *
+     * Removing these markers allows --check to compare only the structural
+     * content (commands, arguments, options, groups) and pass even when the
+     * documentation file was generated at an earlier time.
+     */
+    private function normalizeForCheck(string $content, string $format): string
+    {
+        return match (strtolower($format)) {
+            'json' => (string) preg_replace('/"generated_at"\s*:\s*"[^"]*",?\n?/', '', $content),
+            'html' => (string) preg_replace('/ &mdash; Generated [^<]+/', '', $content),
+            default => (string) preg_replace('/^> Auto-generated on .+$/m', '', $content),
+        };
+    }
 }

tests/Feature/GenerateDocsCommandTest.php

@@ -5,6 +5,7 @@
 use CodeInstinct\ArtisanDocs\Tests\TestCase;
 use Illuminate\Console\Command;
 use Illuminate\Contracts\Console\Kernel;
+use Illuminate\Support\Carbon;
 use Illuminate\Support\Facades\File;
 use Mockery;
 use PHPUnit\Framework\Attributes\Test;
@@ -27,6 +28,9 @@ protected function setUp(): void
 
     protected function tearDown(): void
     {
+        // Reset any frozen Carbon time set by individual tests.
+        Carbon::setTestNow();
+
         if (File::exists(base_path($this->outputPath))) {
             File::delete(base_path($this->outputPath));
         }
@@ -333,4 +337,70 @@ public function it_accepts_a_nested_relative_path_without_traversal(): void
 
         File::delete(base_path($nested));
     }
+
+    // -------------------------------------------------------------------------
+    // --check: timestamp normalisation tests
+    // -------------------------------------------------------------------------
+
+    #[Test]
+    public function it_check_passes_for_markdown_when_only_the_timestamp_has_changed(): void
+    {
+        // Generate the markdown file at time T.
+        Carbon::setTestNow(Carbon::parse('2025-01-01 00:00:00'));
+        $this->artisan('docs:commands', ['--output' => $this->outputPath]);
+
+        // Advance to T + 1 day – the "Auto-generated on …" line will differ,
+        // but the structural content is identical.
+        Carbon::setTestNow(Carbon::parse('2025-01-02 00:00:00'));
+        $this->artisan('docs:commands', [
+            '--output' => $this->outputPath,
+            '--check' => true,
+        ])->assertExitCode(0);
+    }
+
+    #[Test]
+    public function it_check_passes_for_json_when_only_the_timestamp_has_changed(): void
+    {
+        $jsonPath = str_replace('.md', '.json', $this->outputPath);
+
+        // Generate the JSON file at time T.
+        Carbon::setTestNow(Carbon::parse('2025-01-01 00:00:00'));
+        $this->artisan('docs:commands', [
+            '--format' => 'json',
+            '--output' => $jsonPath,
+        ]);
+
+        // Advance time – only "generated_at" will differ.
+        Carbon::setTestNow(Carbon::parse('2025-01-02 00:00:00'));
+        $this->artisan('docs:commands', [
+            '--format' => 'json',
+            '--output' => $jsonPath,
+            '--check' => true,
+        ])->assertExitCode(0);
+
+        File::delete(base_path($jsonPath));
+    }
+
+    #[Test]
+    public function it_check_passes_for_html_when_only_the_timestamp_has_changed(): void
+    {
+        $htmlPath = str_replace('.md', '.html', $this->outputPath);
+
+        // Generate the HTML file at time T.
+        Carbon::setTestNow(Carbon::parse('2025-01-01 00:00:00'));
+        $this->artisan('docs:commands', [
+            '--format' => 'html',
+            '--output' => $htmlPath,
+        ]);
+
+        // Advance time – only the "Generated …" meta suffix will differ.
+        Carbon::setTestNow(Carbon::parse('2025-01-02 00:00:00'));
+        $this->artisan('docs:commands', [
+            '--format' => 'html',
+            '--output' => $htmlPath,
+            '--check' => true,
+        ])->assertExitCode(0);
+
+        File::delete(base_path($htmlPath));
+    }
 }