Fail on log

Currently, when all is well, nothing should be logged at all. We can
leverage this to use the CLI tool as a linter, and create CI jobs with
it.
Here, a new option called --fail-on-log is introduced, and it will use a
failure exit code as soon as any log is emitted.
This is based on the assumption that the logger is never and will never
be called for anything that should not result in a change in the
documentation being processed.

Author: greg0ire

composer.json

@@ -17,6 +17,7 @@
     "autoload-dev": {
         "psr-4": {
             "phpDocumentor\\Guides\\": ["packages/guides/tests/unit/", "tests/"],
+            "phpDocumentor\\Guides\\Cli\\": "packages/guides-cli/tests/unit",
             "phpDocumentor\\Guides\\Graphs\\": "packages/guides-graphs/tests/unit",
             "phpDocumentor\\Guides\\RestructuredText\\": "packages/guides-restructured-text/tests/unit",
             "phpDocumentor\\Guides\\Markdown\\": "packages/guides-markdown/tests/unit"

composer.lock

@@ -11,6 +11,13 @@
             "phpDocumentor\\Guides\\Cli\\": "src/"
         }
     },
+    "autoload-dev": {
+        "psr-4": {
+            "phpDocumentor\\Guides\\": [
+                "tests/unit/"
+            ]
+        }
+    },
     "authors": [
         {
             "name": "jaapio",

packages/guides-cli/composer.json

@@ -11,6 +11,7 @@
 use Monolog\Handler\ErrorLogHandler;
 use Monolog\Handler\StreamHandler;
 use Monolog\Logger;
+use phpDocumentor\Guides\Cli\Logger\SpyProcessor;
 use phpDocumentor\Guides\Compiler\CompilerContext;
 use phpDocumentor\Guides\Handlers\CompileDocumentsCommand;
 use phpDocumentor\Guides\Handlers\ParseDirectoryCommand;
@@ -83,6 +84,12 @@ public function __construct(
             'Write log to this path',
             'php://stder',
         );
+        $this->addOption(
+            'fail-on-log',
+            null,
+            InputOption::VALUE_NONE,
+            'Use a non-zero exit code as soon as any log is written',
+        );
 
         $this->addOption(
             'theme',
@@ -136,6 +143,13 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             $this->logger->pushHandler(new StreamHandler($logPath . '/error.log', Logger::ERROR));
         }
 
+        $failOnLog = $input->getOption('fail-on-log') ?? false;
+
+        if ($failOnLog) {
+            $spyProcessor = new SpyProcessor();
+            $this->logger->pushProcessor($spyProcessor);
+        }
+
         $documents = $this->commandBus->handle(
             new ParseDirectoryCommand(
                 $sourceFileSystem,
@@ -185,7 +199,11 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             'Successfully placed ' . (is_countable($documents) ? count($documents) : 0) . ' rendered ' . $formatsText . ' files into ' . $outputDir,
         );
 
-        return 0;
+        if ($failOnLog && $spyProcessor->hasBeenCalled()) {
+            return Command::FAILURE;
+        }
+
+        return Command::SUCCESS;
     }
 
     private function getAbsolutePath(string $path): string

packages/guides-cli/src/Command/Run.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\Cli\Logger;
+
+use Monolog\Processor\ProcessorInterface;
+
+/**
+ * This decorator has an extra method to check whether anything was logged
+ *
+ * @internal
+ */
+final class SpyProcessor implements ProcessorInterface
+{
+    private bool $hasBeenCalled = false;
+
+    public function hasBeenCalled(): bool
+    {
+        return $this->hasBeenCalled;
+    }
+
+    /** @inheritDoc */
+    public function __invoke(array $record): array
+    {
+        $this->hasBeenCalled = true;
+
+        return $record;
+    }
+}

packages/guides-cli/src/Logger/SpyProcessor.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\Cli\Logger;
+
+use PHPUnit\Framework\TestCase;
+
+class SpyProcessorTest extends TestCase
+{
+    public function testHasBeenCalledReturnsFalseByDefault(): void
+    {
+        $spyProcessor = new SpyProcessor();
+
+        $this->assertFalse($spyProcessor->hasBeenCalled());
+    }
+
+    public function testItKnowsWhenALogIsEmitted(): void
+    {
+        $process = new SpyProcessor();
+        $process(['channel' => 'test']);
+        self::assertTrue($process->hasBeenCalled());
+    }
+}