Configure layer internal tag

baseline.xml

@@ -1,34 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <files psalm-version="5.13.1@086b94371304750d1c673315321a55d15fc59015">
-  <file src="src/Contract/Config/Collector/BoolConfig.php">
-    <ImplementedReturnTypeMismatch>
-      <code><![CDATA[array{
-     *     must: array<array-key, array{private: bool, type: string}>|mixed,
-     *     must_not: array<array-key, array{private: bool, type: string}>|mixed,
-     *     private: bool,
-     *     type: string}]]></code>
-    </ImplementedReturnTypeMismatch>
-  </file>
-  <file src="src/Contract/Config/Collector/ComposerConfig.php">
-    <ImplementedReturnTypeMismatch>
-      <code><![CDATA[array{
-     *     composerPath: string,
-     *     composerLockPath: string,
-     *     packages: list<string>,
-     *     private: bool,
-     *     type: string}]]></code>
-    </ImplementedReturnTypeMismatch>
-  </file>
-  <file src="src/Contract/Config/Collector/SuperGlobalConfig.php">
-    <ImplementedReturnTypeMismatch>
-      <code><![CDATA[array{'private': bool, 'type': string, 'value': string[]}]]></code>
-    </ImplementedReturnTypeMismatch>
-  </file>
-  <file src="src/Contract/Config/ConfigurableCollectorConfig.php">
-    <ImplementedReturnTypeMismatch>
-      <code>array{private: bool, type: string, value: string}</code>
-    </ImplementedReturnTypeMismatch>
-  </file>
   <file src="src/Contract/Result/OutputResult.php">
     <InvalidReturnStatement>
       <code><![CDATA[array_key_exists($type, $this->rules) ? array_values($this->rules[$type]) : []]]></code>

config/services.php

@@ -72,6 +72,7 @@
 use Qossmic\Deptrac\Core\Layer\Collector\MethodCollector;
 use Qossmic\Deptrac\Core\Layer\Collector\PhpInternalCollector;
 use Qossmic\Deptrac\Core\Layer\Collector\SuperglobalCollector;
+use Qossmic\Deptrac\Core\Layer\Collector\TagValueRegexCollector;
 use Qossmic\Deptrac\Core\Layer\Collector\TraitCollector;
 use Qossmic\Deptrac\Core\Layer\Collector\UsesCollector;
 use Qossmic\Deptrac\Core\Layer\LayerResolver;
@@ -258,6 +259,9 @@
     $services
         ->set(ClassNameRegexCollector::class)
         ->tag('collector', ['type' => CollectorType::TYPE_CLASS_NAME_REGEX->value]);
+    $services
+        ->set(TagValueRegexCollector::class)
+        ->tag('collector', ['type' => CollectorType::TYPE_TAG_VALUE_REGEX->value]);
     $services
         ->set(DirectoryCollector::class)
         ->tag('collector', ['type' => CollectorType::TYPE_DIRECTORY->value]);
@@ -336,7 +340,10 @@
         ->tag('kernel.event_subscriber');
     $services
         ->set(DependsOnInternalToken::class)
-        ->tag('kernel.event_subscriber');
+        ->tag('kernel.event_subscriber')
+        ->args([
+            '$config' => param('analyser'),
+        ]);
     $services
         ->set(UnmatchedSkippedViolations::class)
         ->tag('kernel.event_subscriber');

deptrac.config.php

@@ -1,6 +1,7 @@
 <?php
 
 use Internal\Qossmic\Deptrac\IgnoreDependenciesOnContract;
+use Qossmic\Deptrac\Contract\Config\AnalyserConfig;
 use Qossmic\Deptrac\Contract\Config\Collector\BoolConfig;
 use Qossmic\Deptrac\Contract\Config\Collector\ComposerConfig;
 use Qossmic\Deptrac\Contract\Config\Collector\DirectoryConfig;
@@ -18,13 +19,17 @@
 
     $config
         ->paths('src')
-        ->analysers(
-            EmitterType::CLASS_TOKEN,
-            EmitterType::CLASS_SUPERGLOBAL_TOKEN,
-            EmitterType::FILE_TOKEN,
-            EmitterType::FUNCTION_TOKEN,
-            EmitterType::FUNCTION_SUPERGLOBAL_TOKEN,
-            EmitterType::FUNCTION_CALL,
+        ->analyser(
+            AnalyserConfig::create()
+                ->internalTag( '@internal' )
+                ->types(
+                    EmitterType::CLASS_TOKEN,
+                    EmitterType::CLASS_SUPERGLOBAL_TOKEN,
+                    EmitterType::FILE_TOKEN,
+                    EmitterType::FUNCTION_TOKEN,
+                    EmitterType::FUNCTION_SUPERGLOBAL_TOKEN,
+                    EmitterType::FUNCTION_CALL
+                )
         )
         ->layers(
             $analyser = Layer::withName('Analyser')->collectors(

deptrac.yaml

@@ -8,6 +8,7 @@ deptrac:
     - ./src
 
   analyser:
+    internal_tag: "@internal"
     types:
       - class
       - class_superglobal

docs/collectors.md

@@ -97,6 +97,31 @@ deptrac:
 Every class name that matches the regular expression becomes a part of the
 *controller* layer.
 
+## `tagValueRegex` Collector
+
+The `tagValueRegex` collector allows collecting classes and functions by
+matching the name and value of any tag in their phpdoc block, such as @internal
+or @deprecated.
+
+Any matching class will be added to the assigned layer.
+
+```yaml
+deptrac:
+  layers:
+    - name: Deprecated
+      collectors:
+        - type: tagValueRegex
+          tag: '@deprecated'
+    - name: DeprecatedSinceV2
+      collectors:
+        - type: tagValueRegex
+          tag: '@deprecated'
+          value: '/^since v2/i'
+```
+All classes tagged with "@deprecated" become part of the
+*Deprecated* layer. All classes that specify that they have been
+deprecated since v2 also become part of the *DeprecatedSinceV2* layer.
+
 ## `composer` Collector
 
 The `composer` collector allows you to define dependencies on composer `require` or `require-dev` packages that follow PSR-0 or PSR-4 autoloading convention. With this collector you can for example enforce:

docs/configuration.md

@@ -20,6 +20,23 @@ The following table shows the available config keys for Deptrac.
 </thead>
 <tbody>
 <tr>
+<td>analyser.internal_tag</td>
+<td>
+Specifies a custom doc block tag which deptrac should use to identify layer-internal
+class-like structures. The tag <code>@deptrac-internal</code> will always be used
+for this purpose. This option allows an additional tag to be specified, such as
+<code>@layer-internal</code> or plain <code>@internal</code>.
+</td>
+<td>
+
+```yaml
+deptrac:
+  analyser:
+    internal_tag: "@layer-internal"
+```
+</td>
+</tr>
+<tr>
 <td>analyser.types</td>
 <td>
 

src/Contract/Ast/TaggedTokenReferenceInterface.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Qossmic\Deptrac\Contract\Ast;
+
+/**
+ * Represents the AST-Token, its location, and associated tags.
+ */
+interface TaggedTokenReferenceInterface extends TokenReferenceInterface
+{
+    public function hasTag(string $name): bool;
+
+    /**
+     * @return ?list<string>
+     */
+    public function getTagLines(string $name): ?array;
+}

src/Contract/Config/AnalyserConfig.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Qossmic\Deptrac\Contract\Config;
+
+final class AnalyserConfig
+{
+    /** @var array<string, EmitterType> */
+    private array $types = [];
+
+    /** @var ?string */
+    private ?string $internalTag = null;
+
+    private function __construct() {}
+
+    /** @param ?array<array-key,EmitterType> $types */
+    public static function create(array $types = null, string $internalTag = null): self
+    {
+        $analyser = new self();
+
+        $types ??= [EmitterType::CLASS_TOKEN, EmitterType::FUNCTION_TOKEN];
+        $analyser->types(...$types);
+
+        $analyser->internalTag($internalTag);
+
+        return $analyser;
+    }
+
+    public function types(EmitterType ...$types): self
+    {
+        $this->types = [];
+        foreach ($types as $type) {
+            $this->types[$type->value] = $type;
+        }
+
+        return $this;
+    }
+
+    public function internalTag(?string $tag): self
+    {
+        $this->internalTag = $tag;
+
+        return $this;
+    }
+
+    /** @return array<string, mixed> */
+    public function toArray(): array
+    {
+        return [
+            'types' => array_map(static fn (EmitterType $emitterType) => $emitterType->value, $this->types),
+            'internal_tag' => $this->internalTag,
+        ];
+    }
+}

src/Contract/Config/Collector/TagValueRegexConfig.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Qossmic\Deptrac\Contract\Config\Collector;
+
+use Qossmic\Deptrac\Contract\Config\CollectorConfig;
+use Qossmic\Deptrac\Contract\Config\CollectorType;
+
+final class TagValueRegexConfig extends CollectorConfig
+{
+    protected CollectorType $collectorType = CollectorType::TYPE_TAG_VALUE_REGEX;
+
+    public function __construct(
+        private string $tag,
+        private ?string $value = null
+    ) {}
+
+    public static function create(string $tag, string $regexpr = null): self
+    {
+        return new self($tag, $regexpr);
+    }
+
+    public function match(string $regexpr): self
+    {
+        $this->value = $regexpr;
+
+        return $this;
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'tag' => $this->tag,
+            'value' => $this->value,
+        ] + parent::toArray();
+    }
+}

src/Contract/Config/CollectorConfig.php

@@ -16,8 +16,8 @@
         return $this;
     }
 
-    /** @return array{'type': string, 'private': bool} */
+    /** @return array{'type': string, 'private': bool, ...} */
     public function toArray(): array
     {
         return [
             'type' => $this->collectorType->value,

src/Contract/Config/CollectorType.php

@@ -12,6 +12,7 @@ enum CollectorType: string
     case TYPE_CLASS = 'class';
     case TYPE_CLASSLIKE = 'classLike';
     case TYPE_CLASS_NAME_REGEX = 'classNameRegex';
+    case TYPE_TAG_VALUE_REGEX = 'tagValueRegex';
     case TYPE_DIRECTORY = 'directory';
     case TYPE_EXTENDS = 'extends';
     case TYPE_FUNCTION_NAME = 'functionName';

src/Contract/Config/DeptracConfig.php

@@ -21,18 +21,23 @@
     private array $formatters = [];
     /** @var array<Ruleset> */
     private array $rulesets = [];
-    /** @var array<string, EmitterType> */
-    private array $analyser = [];
+    private ?AnalyserConfig $analyser = null;
     /** @var array<string, array<string>> */
     private array $skipViolations = [];
     /** @var array<string> */
     private array $excludeFiles = [];
 
+    /**
+     * @deprecated use analyser(AnalyserConfig::create()) instead
+     */
     public function analysers(EmitterType ...$types): self
     {
-        foreach ($types as $type) {
-            $this->analyser[$type->value] = $type;
-        }
+        return $this->analyser(AnalyserConfig::create($types));
+    }
+
+    public function analyser(AnalyserConfig $analyser): self
+    {
+        $this->analyser = $analyser;
 
         return $this;
     }
@@ -109,15 +114,15 @@
             $config['paths'] = $this->paths;
         }
 
-        if ([] !== $this->analyser) {
-            $config['analyser']['types'] = array_map(static fn (EmitterType $emitterType) => $emitterType->value, $this->analyser);
+        if ($this->analyser) {
+            $config['analyser'] = $this->analyser->toArray();
         }
 
         if ([] !== $this->formatters) {
             $config['formatters'] = array_map(static fn (FormatterConfigInterface $formatterConfig) => $formatterConfig->toArray(), $this->formatters);
         }
 
         if ([] !== $this->excludeFiles) {
             $config['exclude_files'] = $this->excludeFiles;
         }
 
@@ -129,13 +134,13 @@
             $config['ruleset'] = array_map(static fn (Ruleset $rulesetConfig) => $rulesetConfig->toArray(), $this->rulesets);
         }
 
         if ([] !== $this->skipViolations) {
             $config['skip_violations'] = $this->skipViolations;
         }
 
         $config['ignore_uncovered_internal_classes'] = $this->ignoreUncoveredInternalClasses;
 
         return $config;
     }
 
     public function getExtensionAlias(): string

src/Core/Analyser/EventHandler/DependsOnInternalToken.php

@@ -14,7 +14,17 @@
  */
 class DependsOnInternalToken implements ViolationCreatingInterface
 {
-    public function __construct(private readonly EventHelper $eventHelper) {}
+    private ?string $internalTag;
+
+    /**
+     * @param array{internal_tag:string|null, ...} $config
+     */
+    public function __construct(
+        private readonly EventHelper $eventHelper,
+        array $config)
+    {
+        $this->internalTag = $config['internal_tag'];
+    }
 
     public static function getSubscribedEvents()
     {
@@ -29,10 +39,17 @@
         foreach ($event->dependentLayers as $dependentLayer => $_) {
             if ($event->dependerLayer !== $dependentLayer
                 && $event->dependentReference instanceof ClassLikeReference
-                && $event->dependentReference->isInternal
             ) {
-                $this->eventHelper->addSkippableViolation($event, $ruleset, $dependentLayer, $this);
-                $event->stopPropagation();
+                $isInternal = $event->dependentReference->hasTag('@deptrac-internal');
+
+                if (!$isInternal && null !== $this->internalTag) {
+                    $isInternal = $event->dependentReference->hasTag($this->internalTag);
+                }
+
+                if ($isInternal) {
+                    $this->eventHelper->addSkippableViolation($event, $ruleset, $dependentLayer, $this);
+                    $event->stopPropagation();
+                }
             }
         }
     }