Merge branch 'main' into code-block-whitespace

Author: jaapio

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"
@@ -52,6 +53,7 @@
         "dealerdirect/phpcodesniffer-composer-installer": "^1.0",
         "doctrine/coding-standard": "^12.0",
         "fakerphp/faker": "^1.23",
+        "fig/log-test": "^1.0",
         "gajus/dindent": "^2.0.1",
         "jangregor/phpstan-prophecy": "^1.0",
         "league/flysystem-memory": "^1.0",

composer.lock

@@ -8,22 +8,26 @@ This library uses a simplified compiler design. This basically means that our pi
 than a regular compiler. But its following the same semantics.
 
 Lexing and Parsing
+==================
 
-A typical compiler will have separate lexing, syntax analisys. However the parser
-was designed to do part of the lexing because of all context dependend logic of most Markup languages.
+A typical compiler will have separate lexing, syntax analysis. However the parser
+was designed to do part of the lexing because of all context-dependent logic of most Markup languages.
 We call this the parsing phase. This will result into an AST that is mostly close to the original source. It
 might contain some optimizations for later use.
 
 Semantic analysis and Intermediate code generation
+==================================================
 
 The semantic analysis phase of this library is performing a number of steps to collect information of the parsed markup
-language. An good example is the collection of the table of contents and the metadata of the parsed documents.
+language. A good example is the collection of the table of contents and the metadata of the parsed documents.
 This is the moment where document node traversers are executed.
 
 Code optimization
+=================
 
 Do some pre-rendering stuff, like buiding the TOC content and other rendering preparations before the real rendering starts.
 
 Code generation
+===============
 
-Code generation a.k. rendering. We do deliver a headless
+Code generation a.k.a. rendering. We do deliver a headless

docs/components/compiler.rst

@@ -4,6 +4,28 @@
 Extending the phpdocumentor/guides
 ==================================
 
+``phpdocumentor/guides`` relies on `Symfony Dependency Injection
+Container
+<https://symfony.com/doc/current/components/dependency_injection.html#setting-up-the-container-with-configuration-files>`__
+extensions. This means that to extend the guides, you need to define
+such an extension, after what it becomes possible to make the guides CLI
+aware of it by creating a ``guides.xml`` file in the directory from
+which you invoke the CLI.
+
+It should look like this::
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="UTF-8" ?>
+    <guides>
+        <extension class="YourName\YourExtension\DependencyInjection\YourExtension"/>
+    </guides>
+
+Internally, the guides CLI defines and uses default extensions.
+Once you have that set up, you can create PHP classes, define services
+from it, and tag them so that they are recognized and usable by the
+guides CLI.
+
 Some ways to extend the guides:
 
 .. toctree::

docs/extension/index.rst

@@ -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

@@ -97,12 +97,12 @@ private function resolveExtensionClass(string $name): string
 
             $fqcn = implode('\\', [$fqcn, 'DependencyInjection', $package . 'Extension']);
             if (!class_exists($fqcn)) {
-                throw new LogicException(sprintf('Extension "%s" does not exists.', $fqcn));
+                throw new LogicException(sprintf('Extension "%s" does not exist.', $fqcn));
             }
         }
 
         if (!is_a($fqcn, ExtensionInterface::class, true)) {
-            throw new LogicException(sprintf('Extension "%s" does not exists.', $fqcn));
+            throw new LogicException(sprintf('Extension "%s" does not exist.', $fqcn));
         }
 
         return $fqcn;

packages/guides-cli/src/DependencyInjection/ContainerFactory.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());
+    }
+}

packages/guides-cli/tests/unit/Logger/SpyProcessorTest.php

@@ -10,6 +10,7 @@
 use phpDocumentor\Guides\RestructuredText\Directives\BaseDirective;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
+use Psr\Log\LoggerInterface;
 use Webmozart\Assert\Assert;
 
 use function dirname;
@@ -34,6 +35,10 @@
  */
 final class UmlDirective extends BaseDirective
 {
+    public function __construct(private readonly LoggerInterface $logger)
+    {
+    }
+
     public function getName(): string
     {
         return 'uml';
@@ -72,9 +77,11 @@ private function loadExternalUmlFile(ParserContext $parserContext, string $path)
         );
 
         if (!$parserContext->getOrigin()->has($fileName)) {
-            $parserContext->addError(
-                sprintf('Tried to include "%s" as a diagram but the file could not be found', $fileName),
-            );
+            $message =
+                sprintf('Tried to include "%s" as a diagram but the file could not be found', $fileName);
+
+
+            $this->logger->error($message, $parserContext->getLoggerInformation());
 
             return null;
         }