Add deprecation trigger for context extension

Author: jaapio

composer.json

@@ -36,6 +36,7 @@
         "php": "^8.1",
         "ext-json": "*",
         "ext-mbstring": "*",
+        "doctrine/deprecations": "^1.1",
         "phpdocumentor/guides": "^1.0@dev || ^0.3",
         "phpdocumentor/guides-cli": "^1.0@dev || ^0.3",
         "phpdocumentor/guides-code": "^1.0@dev || ^0.3",

composer.lock

@@ -24,6 +24,7 @@
         "php": "^8.1",
         "ext-json": "*",
         "ext-zlib": "*",
+        "doctrine/deprecations": "^1.0",
         "league/flysystem": "^1.1",
         "league/tactician": "^1.1",
         "league/uri": "^6.5 || ^7.0",

packages/guides/composer.json

@@ -13,6 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler;
 
+use Doctrine\Deprecations\Deprecation;
 use Exception;
 use phpDocumentor\Guides\Compiler\ShadowTree\TreeNode;
 use phpDocumentor\Guides\Nodes\DocumentNode;
@@ -38,6 +39,15 @@ class CompilerContext implements CompilerContextInterface
     public function __construct(
         private readonly ProjectNode $projectNode,
     ) {
+        if (self::class === static::class) {
+            return;
+        }
+
+        Deprecation::trigger(
+            'phpdocumentor/guides',
+            'https://github.com/phpDocumentor/guides/issues/971',
+            'Extending CompilerContext is deprecated, please use the CompilerContextInterface instead.',
+        );
     }
 
     public function getProjectNode(): ProjectNode

packages/guides/src/Compiler/CompilerContext.php

@@ -14,7 +14,6 @@
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
 use phpDocumentor\Guides\Compiler\CompilerContext;
-use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\CompilerPass;
 use phpDocumentor\Guides\Compiler\DocumentNodeTraverser;
 use phpDocumentor\Guides\Nodes\DocumentNode;

packages/guides/src/Compiler/NodeTransformers/TransformerPass.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides\Compiler;
+
+use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
+use phpDocumentor\Guides\Nodes\ProjectNode;
+use PHPUnit\Framework\TestCase;
+
+final class CompilerContextTest extends TestCase
+{
+    use VerifyDeprecations;
+
+    public function testTriggersDeprecationOnContextExtend(): void
+    {
+        $this->expectDeprecationWithIdentifier('https://github.com/phpDocumentor/guides/issues/971');
+        $context = new class (new ProjectNode()) extends CompilerContext{
+        };
+    }
+
+    public function testNoDeprecationOnNormalConstruct(): void
+    {
+        $this->expectNoDeprecationWithIdentifier('https://github.com/phpDocumentor/guides/issues/971');
+        $context = new CompilerContext(new ProjectNode());
+    }
+}

packages/guides/tests/unit/Compiler/CompilerContextTest.php

@@ -120,6 +120,16 @@ parameters:
 			count: 1
 			path: packages/guides-restructured-text/src/RestructuredText/Parser/Productions/ListRule.php
 
+		-
+			message: "#^Strict comparison using \\=\\=\\= between 'phpDocumentor\\\\\\\\Guides\\\\\\\\Compiler\\\\\\\\CompilerContext' and 'phpDocumentor\\\\\\\\Guides\\\\\\\\Compiler\\\\\\\\CompilerContext' will always evaluate to true\\.$#"
+			count: 1
+			path: packages/guides/src/Compiler/CompilerContext.php
+
+		-
+			message: "#^Unreachable statement \\- code above always terminates\\.$#"
+			count: 1
+			path: packages/guides/src/Compiler/CompilerContext.php
+
 		-
 			message: "#^Function Symfony\\\\Component\\\\DependencyInjection\\\\Loader\\\\Configurator\\\\tagged_iterator not found\\.$#"
 			count: 2
@@ -140,6 +150,11 @@ parameters:
 			count: 1
 			path: packages/guides/src/Renderer/DocumentListIterator.php
 
+		-
+			message: "#^Anonymous class extends @final class phpDocumentor\\\\Guides\\\\Compiler\\\\CompilerContext\\.$#"
+			count: 1
+			path: packages/guides/tests/unit/Compiler/CompilerContextTest.php
+
 		-
 			message: "#^Return type \\(iterable\\<phpDocumentor\\\\Guides\\\\Compiler\\\\NodeTransformers\\\\MoveAnchorTransformer\\>\\) of method class@anonymous/packages/guides/tests/unit/Compiler/NodeTransformers/MoveAnchorTransformerTest\\.php\\:32\\:\\:getTransformers\\(\\) should be compatible with return type \\(iterable\\<phpDocumentor\\\\Guides\\\\Compiler\\\\NodeTransformer\\<phpDocumentor\\\\Guides\\\\Nodes\\\\Node\\>\\>\\) of method phpDocumentor\\\\Guides\\\\Compiler\\\\NodeTransformers\\\\NodeTransformerFactory\\:\\:getTransformers\\(\\)$#"
 			count: 1

phpstan-baseline.neon

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<files psalm-version="5.22.2@d768d914152dbbf3486c36398802f74e80cfde48">
+<files psalm-version="5.23.1@8471a896ccea3526b26d082f4461eeea467f10a4">
   <file src="packages/guides-cli/src/Config/Configuration.php">
     <UndefinedMethod>
       <code><![CDATA[ignoreExtraKeys]]></code>
@@ -55,6 +55,11 @@
       <code><![CDATA[$result->value]]></code>
     </InvalidPropertyAssignmentValue>
   </file>
+  <file src="packages/guides/tests/unit/Compiler/CompilerContextTest.php">
+    <InvalidExtendClass>
+      <code><![CDATA[CompilerContext]]></code>
+    </InvalidExtendClass>
+  </file>
   <file src="packages/guides/tests/unit/Compiler/NodeTransformers/DocumentEntryRegistrationTransformerTest.php">
     <InvalidArgument>
       <code><![CDATA[[new SectionNode(TitleNode::emptyNode())]]]></code>