Merge pull request #3488 from phpDocumentor/move-compiling-into-pipeline

Move compiling into a pipeline
phpDocumentor · Mar 23, 2023 · ea824e6 · ea824e6
2 parents 4247244 + cd5573d
commit ea824e6
Show file tree

Hide file tree

Showing 33 changed files with 336 additions and 290 deletions.
diff --git a/config/pipelines.yaml b/config/pipelines.yaml
@@ -1,33 +1,40 @@
 services:
+    phpDocumentor\Pipeline\PipelineFactory: ~
+
     # Will call all pipeline and stages tagged with 'phpdoc.pipeline.api_documentation.generate',
     # this includes both the parse and transform pipeline
     phpdoc.complete.pipeline:
       class: 'League\Pipeline\Pipeline'
-      factory: ['phpDocumentor\Pipeline\PipelineFactory', 'create']
+      factory: ['@phpDocumentor\Pipeline\PipelineFactory', 'create']
       arguments: [!tagged phpdoc.pipeline.api_documentation.generate]
 
     phpdoc.configuration.pipeline:
       class: 'League\Pipeline\Pipeline'
-      factory: ['phpDocumentor\Pipeline\PipelineFactory', 'create']
+      factory: ['@phpDocumentor\Pipeline\PipelineFactory', 'create']
       arguments: [!tagged phpdoc.pipeline.application.configuration]
       tags:
         - { name: 'phpdoc.pipeline.api_documentation.generate', priority: 10000 }
 
     phpdoc.parse.pipeline:
       class: 'League\Pipeline\Pipeline'
-      factory: ['phpDocumentor\Pipeline\PipelineFactory', 'create']
+      factory: ['@phpDocumentor\Pipeline\PipelineFactory', 'create']
       arguments: [!tagged phpdoc.pipeline.api_documentation.parse]
       tags:
         - { name: 'phpdoc.pipeline.api_documentation.generate', priority: 8000 }
 
     phpdoc.parse_api_documentation_set.pipeline:
       class: 'League\Pipeline\Pipeline'
-      factory: ['phpDocumentor\Pipeline\PipelineFactory', 'create']
+      factory: ['@phpDocumentor\Pipeline\PipelineFactory', 'create']
       arguments: [!tagged phpdoc.pipeline.api_documentation.parse_api_documentation_set]
 
+    phpdoc.compile.pipeline:
+      class: 'League\Pipeline\Pipeline'
+      factory: ['@phpDocumentor\Pipeline\PipelineFactory', 'create']
+      arguments: [!tagged phpdoc.pipeline.api_documentation.compile]
+
     phpdoc.transform.pipeline:
       class: 'League\Pipeline\Pipeline'
-      factory: ['phpDocumentor\Pipeline\PipelineFactory', 'create']
+      factory: ['@phpDocumentor\Pipeline\PipelineFactory', 'create']
       arguments: [!tagged phpdoc.pipeline.api_documentation.transform]
       tags:
         - { name: 'phpdoc.pipeline.api_documentation.generate', priority: 5000 }
diff --git a/config/services.yaml b/config/services.yaml
@@ -4,61 +4,6 @@ imports:
   - { resource: 'stages.yaml' }
   - { resource: 'guides.yaml' }
 
-parameters:
-    linker.substitutions:
-      'phpDocumentor\Descriptor\ProjectDescriptor': ['files']
-      'phpDocumentor\Descriptor\FileDescriptor':
-          - 'tags'
-          - 'classes'
-          - 'interfaces'
-          - 'traits'
-          - 'functions'
-          - 'constants'
-      'phpDocumentor\Descriptor\ClassDescriptor':
-          - 'tags'
-          - 'parent'
-          - 'interfaces'
-          - 'constants'
-          - 'properties'
-          - 'methods'
-          - 'usedTraits'
-      'phpDocumentor\Descriptor\InterfaceDescriptor':
-          - 'tags'
-          - 'parent'
-          - 'constants'
-          - 'methods'
-      'phpDocumentor\Descriptor\TraitDescriptor':
-          - 'tags'
-          - 'properties'
-          - 'methods'
-          - 'usedTraits'
-      'phpDocumentor\Descriptor\EnumDescriptor':
-        - 'tags'
-        - 'interfaces'
-        - 'cases'
-        - 'methods'
-        - 'usedTraits'
-      'phpDocumentor\Descriptor\FunctionDescriptor':
-          - 'tags'
-          - 'arguments'
-      'phpDocumentor\Descriptor\MethodDescriptor':
-          - 'tags'
-          - 'arguments'
-      'phpDocumentor\Descriptor\ArgumentDescriptor':
-          - 'type'
-      'phpDocumentor\Descriptor\PropertyDescriptor':
-          - 'tags'
-          - 'type'
-      'phpDocumentor\Descriptor\ConstantDescriptor':
-          - 'tags'
-          - 'type'
-      'phpDocumentor\Descriptor\Tag\ParamDescriptor': ['type']
-      'phpDocumentor\Descriptor\Tag\VarDescriptor': ['type']
-      'phpDocumentor\Descriptor\Tag\ReturnDescriptor': ['type']
-      'phpDocumentor\Descriptor\Tag\SeeDescriptor': ['reference']
-      'phpDocumentor\Descriptor\Tag\UsesDescriptor': ['reference']
-      'phpDocumentor\Descriptor\Tag\UsedByDescriptor': ['reference']
-
 services:
     _defaults:
         autowire: true
@@ -90,6 +35,8 @@ services:
     phpDocumentor\:
         resource: '../src/phpDocumentor/*'
         exclude:
+          - '../src/phpDocumentor/Linker/Linker'
+          - '../src/phpDocumentor/Compiler'
           - '../src/phpDocumentor/**/Messages'
           - '../src/phpDocumentor/Pipeline/Stage'
           - '../src/phpDocumentor/Transformer/**/{Event, Exception}/{**}'
@@ -111,9 +58,6 @@ services:
         resource: '../src/phpDocumentor/Transformer'
         exclude: '../src/phpDocumentor/Transformer/**/{Event, Exception}/{**}'
 
-    phpDocumentor\Compiler\:
-        resource: '../src/phpDocumentor/Compiler'
-
     ###################################################################################
     ## Autoloading definitions for individual classes #################################
     ###################################################################################
@@ -160,23 +104,6 @@ services:
             '2': '@phpDocumentor\Configuration\Definition\Version2'
             '3': '@phpDocumentor\Configuration\Definition\Version3'
 
-    phpDocumentor\Compiler\Linker\Linker:
-        arguments: ['%linker.substitutions%']
-
-    phpDocumentor\Compiler\Compiler:
-        calls:
-            - [insert, ['@phpDocumentor\Compiler\Pass\GuidesCompiler', 3000]]
-            - [insert, ['@phpDocumentor\Compiler\Pass\TableOfContentsBuilder', 2000]]
-            - [insert, ['@phpDocumentor\Compiler\Pass\ElementsIndexBuilder', !php/const \phpDocumentor\Compiler\Pass\ElementsIndexBuilder::COMPILER_PRIORITY]]
-            - [insert, ['@phpDocumentor\Compiler\Pass\MarkerFromTagsExtractor', !php/const \phpDocumentor\Compiler\Pass\MarkerFromTagsExtractor::COMPILER_PRIORITY]]
-            - [insert, ['@phpDocumentor\Compiler\Pass\PackageTreeBuilder', !php/const \phpDocumentor\Compiler\Pass\PackageTreeBuilder::COMPILER_PRIORITY]]
-            - [insert, ['@phpDocumentor\Compiler\Pass\NamespaceTreeBuilder', !php/const \phpDocumentor\Compiler\Pass\NamespaceTreeBuilder::COMPILER_PRIORITY]]
-            - [insert, ['@phpDocumentor\Compiler\Pass\ResolveInlineMarkers', !php/const \phpDocumentor\Compiler\Pass\ResolveInlineMarkers::COMPILER_PRIORITY]]
-            - [insert, ['@phpDocumentor\Compiler\Pass\UsedByBuilder', !php/const \phpDocumentor\Compiler\Pass\ResolveInlineMarkers::COMPILER_PRIORITY]]
-            - [insert, ['@phpDocumentor\Compiler\Pass\Debug', !php/const \phpDocumentor\Compiler\Pass\Debug::COMPILER_PRIORITY]]
-            - [insert, ['@phpDocumentor\Compiler\Pass\RemoveSourcecode',!php/const \phpDocumentor\Compiler\Pass\RemoveSourcecode::COMPILER_PRIORITY]]
-            - [insert, ['@phpDocumentor\Compiler\Linker\Linker', !php/const \phpDocumentor\Compiler\Linker\Linker::COMPILER_PRIORITY]]
-
     phpDocumentor\Parser\Parser: ~
 
     phpDocumentor\Reflection\DocBlock\ExampleFinder: ~

diff --git a/config/stages.yaml b/config/stages.yaml
@@ -1,8 +1,66 @@
+parameters:
+  linker.substitutions:
+    'phpDocumentor\Descriptor\ProjectDescriptor': ['files']
+    'phpDocumentor\Descriptor\FileDescriptor':
+      - 'tags'
+      - 'classes'
+      - 'interfaces'
+      - 'traits'
+      - 'functions'
+      - 'constants'
+    'phpDocumentor\Descriptor\ClassDescriptor':
+      - 'tags'
+      - 'parent'
+      - 'interfaces'
+      - 'constants'
+      - 'properties'
+      - 'methods'
+      - 'usedTraits'
+    'phpDocumentor\Descriptor\InterfaceDescriptor':
+      - 'tags'
+      - 'parent'
+      - 'constants'
+      - 'methods'
+    'phpDocumentor\Descriptor\TraitDescriptor':
+      - 'tags'
+      - 'properties'
+      - 'methods'
+      - 'usedTraits'
+    'phpDocumentor\Descriptor\EnumDescriptor':
+      - 'tags'
+      - 'interfaces'
+      - 'cases'
+      - 'methods'
+      - 'usedTraits'
+    'phpDocumentor\Descriptor\FunctionDescriptor':
+      - 'tags'
+      - 'arguments'
+    'phpDocumentor\Descriptor\MethodDescriptor':
+      - 'tags'
+      - 'arguments'
+    'phpDocumentor\Descriptor\ArgumentDescriptor':
+      - 'type'
+    'phpDocumentor\Descriptor\PropertyDescriptor':
+      - 'tags'
+      - 'type'
+    'phpDocumentor\Descriptor\ConstantDescriptor':
+      - 'tags'
+      - 'type'
+    'phpDocumentor\Descriptor\Tag\ParamDescriptor': ['type']
+    'phpDocumentor\Descriptor\Tag\VarDescriptor': ['type']
+    'phpDocumentor\Descriptor\Tag\ReturnDescriptor': ['type']
+    'phpDocumentor\Descriptor\Tag\SeeDescriptor': ['reference']
+    'phpDocumentor\Descriptor\Tag\UsesDescriptor': ['reference']
+    'phpDocumentor\Descriptor\Tag\UsedByDescriptor': ['reference']
+
 services:
   _defaults:
     autowire: true
     autoconfigure: true
 
+  phpDocumentor\Compiler\:
+    resource: '../src/phpDocumentor/Compiler'
+
   phpDocumentor\Pipeline\Stage\Configure:
     arguments:
       $currentWorkingDir: "@=service('kernel').getWorkingDir()"
@@ -61,11 +119,62 @@ services:
     tags:
       - { name: 'phpdoc.pipeline.api_documentation.parse_api_documentation_set', priority: 0 }
 
+  ###################################################################################
+  ## Autoloading definitions for compiler stages    #################################
+  ###################################################################################
+
+  phpDocumentor\Compiler\Pass\ElementsIndexBuilder:
+    tags:
+      - { name: 'phpdoc.pipeline.api_documentation.compile', priority: 15000 }
+
+  phpDocumentor\Compiler\Linker\Linker:
+    arguments: ['%linker.substitutions%']
+    tags:
+      - { name: 'phpdoc.pipeline.api_documentation.compile', priority: 10000 }
+
+  phpDocumentor\Compiler\Pass\PackageTreeBuilder:
+    tags:
+      - { name: 'phpdoc.pipeline.api_documentation.compile', priority: 9001 }
+
+  phpDocumentor\Compiler\Pass\MarkerFromTagsExtractor:
+    tags:
+      - { name: 'phpdoc.pipeline.api_documentation.compile', priority: 9000 }
+
+  phpDocumentor\Compiler\Pass\NamespaceTreeBuilder:
+    tags:
+      - { name: 'phpdoc.pipeline.api_documentation.compile', priority: 9000 }
+
+  phpDocumentor\Compiler\Pass\ResolveInlineMarkers:
+    tags:
+      - { name: 'phpdoc.pipeline.api_documentation.compile', priority: 9000 }
+
+  phpDocumentor\Compiler\Pass\UsedByBuilder:
+    tags:
+      - { name: 'phpdoc.pipeline.api_documentation.compile', priority: 9000 }
+
+  phpDocumentor\Compiler\Pass\GuidesCompiler:
+    tags:
+      - { name: 'phpdoc.pipeline.api_documentation.compile', priority: 3000 }
+
+  phpDocumentor\Compiler\Pass\RemoveSourcecode:
+    tags:
+      - { name: 'phpdoc.pipeline.api_documentation.compile', priority: 2000 }
+
+  phpDocumentor\Compiler\Pass\TableOfContentsBuilder:
+    tags:
+      - { name: 'phpdoc.pipeline.api_documentation.compile', priority: 2000 }
+
+  phpDocumentor\Compiler\Pass\Debug:
+    tags:
+      - { name: 'phpdoc.pipeline.api_documentation.compile', priority: 1000 }
+
   ###################################################################################
   ## Autoloading definitions for transform stages   #################################
   ###################################################################################
 
   phpDocumentor\Pipeline\Stage\Compile:
+    arguments:
+      $compilerPipeline: '@phpdoc.compile.pipeline'
     tags:
       - { name: 'phpdoc.pipeline.api_documentation.transform', priority: 5000 }
 

diff --git a/psalm.xml b/psalm.xml
@@ -70,12 +70,6 @@
             </errorLevel>
         </InvalidThrow>
 
-        <TooManyTemplateParams>
-            <errorLevel type="suppress">
-                <file name="src/phpDocumentor/Compiler/Compiler.php"/>
-            </errorLevel>
-        </TooManyTemplateParams>
-
         <DeprecatedClass>
             <errorLevel type="suppress">
                 <!-- MountManager will be removed in Flysystem V2 -->

diff --git a/src/phpDocumentor/Compiler/Compiler.php b/src/phpDocumentor/Compiler/Compiler.php
diff --git a/src/phpDocumentor/Compiler/CompilerPassInterface.php b/src/phpDocumentor/Compiler/CompilerPassInterface.php
@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Compiler;
 
-use phpDocumentor\Descriptor\ProjectDescriptor;
+use phpDocumentor\Descriptor\Interfaces\ProjectInterface;
 
 /**
  * Represents a single pass / business rule to be executed by the Compiler.
@@ -34,7 +34,7 @@ public function getDescription(): string;
      * This method will execute the business logic associated with a given compiler pass and allow it to manipulate
      * or consumer the Object Graph using the ProjectDescriptor object.
      *
-     * @param ProjectDescriptor $project Representation of the Object Graph that can be manipulated.
+     * @param ProjectInterface $project Representation of the Object Graph that can be manipulated.
      */
-    public function execute(ProjectDescriptor $project): void;
+    public function __invoke(ProjectInterface $project): ProjectInterface;
 }
diff --git a/src/phpDocumentor/Compiler/Linker/Linker.php b/src/phpDocumentor/Compiler/Linker/Linker.php
@@ -81,10 +81,12 @@ public function __construct(array $substitutions, DescriptorRepository $descript
         $this->descriptorRepository = $descriptorRepository;
     }
 
-    public function execute(ProjectInterface $project): void
+    public function __invoke(ProjectInterface $project): ProjectInterface
     {
         $this->descriptorRepository->setObjectAliasesList($project->getIndexes()->get('elements')->getAll());
         $this->substitute($project);
+
+        return $project;
     }
 
     /**
@@ -122,9 +124,9 @@ public function getSubstitutions(): array
      * This method will return null if no substitution was possible and all of the above should not update the parent
      * item when null is passed.
      *
-     * @param string|Fqsen|Type|Collection<mixed>|array<mixed>|Descriptor $item
+     * @param string|Fqsen|Type|Collection<mixed>|array<mixed>|Descriptor|ProjectInterface $item
      *
-     * @return string|DescriptorAbstract|Collection<string|DescriptorAbstract>|array<string|DescriptorAbstract>|null
+     * @return string|ProjectInterface|DescriptorAbstract|Collection<string|DescriptorAbstract>|array<string|DescriptorAbstract>|null
      */
     public function substitute($item, ?DescriptorAbstract $container = null)
     {