Replace @public PHPDoc with #[Exposed] attribute

README.md

@@ -59,11 +59,11 @@ $http = PhpModules\Lib\Module::strict('App\Http', [$persistence]);
 return Modules::builder('./src')->register([$persistence, $http])
 ```
 
-Mark classes as public using PHPDoc:
+Mark classes as public using the `#[Exposed]` attribute:
 ```php
-/**
- * @public
- */
+use PhpModules\Attributes\Exposed;
+
+#[Exposed]
 class PersistedUser {}
 ```
 

src/Attributes/Exposed.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace PhpModules\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS)]
+class Exposed
+{
+}

src/Cli/Cli.php

@@ -2,9 +2,9 @@
 
 namespace PhpModules\Cli;
 
-/**
- * @public
- */
+use PhpModules\Attributes\Exposed;
+
+#[Exposed]
 class Cli
 {
 

src/DocReader/DocReader.php

@@ -3,35 +3,17 @@
 namespace PhpModules\DocReader;
 
 
+use PhpModules\Attributes\Exposed;
 use PHPStan\PhpDocParser\Lexer\Lexer;
 use PHPStan\PhpDocParser\Parser\ConstExprParser;
 use PHPStan\PhpDocParser\Parser\ParserException;
 use PHPStan\PhpDocParser\Parser\PhpDocParser;
 use PHPStan\PhpDocParser\Parser\TokenIterator;
 use PHPStan\PhpDocParser\Parser\TypeParser;
 
-/**
- * @public
- */
+#[Exposed]
 class DocReader
 {
-
-    public function isPublic(?string $phpdoc): bool
-    {
-        if ($phpdoc === null) {
-            return false;
-        }
-        $phpdoc = $this->prepare($phpdoc);
-        $lexer = new Lexer();
-        $constExprParser = new ConstExprParser();
-        $phpDocParser = new PhpDocParser(new TypeParser($constExprParser), $constExprParser);
-        $tokenize = $lexer->tokenize($phpdoc);
-
-        $phpDocNode = $phpDocParser->parse(new TokenIterator($tokenize));
-
-        return count($phpDocNode->getTagsByName('@public')) > 0;
-    }
-
     public function isIgnoredImport(?string $phpdoc): bool
     {
         if ($phpdoc === null) {

src/Exceptions/PHPModulesException.php

@@ -2,10 +2,10 @@
 
 namespace PhpModules\Exceptions;
 
-/**
- * @public
- */
+use PhpModules\Attributes\Exposed;
+
+#[Exposed]
 class PHPModulesException extends \Exception
 {
 
-}
+}

src/Lib/AnalysisResult.php

@@ -2,11 +2,10 @@
 
 namespace PhpModules\Lib;
 
+use PhpModules\Attributes\Exposed;
 use PhpModules\Lib\Errors\Error;
 
-/**
- * @public
- */
+#[Exposed]
 class AnalysisResult
 {
     /**

src/Lib/Analyzer.php

@@ -2,6 +2,7 @@
 
 namespace PhpModules\Lib;
 
+use PhpModules\Attributes\Exposed;
 use PhpModules\DocReader\DocReader;
 use PhpModules\Exceptions\PHPModulesException;
 use PhpModules\Lib\Domain\ClassName;
@@ -18,11 +19,18 @@
 use PhpModules\Lib\Internal\SingleDependency;
 use ReflectionClass;
 
-/**
- * @public
- */
+#[Exposed]
 class Analyzer
 {
+    /**
+     * Imports that are always allowed regardless of module configuration.
+     * Matched as namespace parents, so any class under these namespaces is ignored.
+     */
+    private const GLOBAL_IGNORED_NAMESPACES = [
+        'PhpModules\\Attributes',
+        'Closure',
+    ];
+
     /**
      * @param Modules $modules
      * @param FileDefinition[] $fileDefinitions
@@ -86,6 +94,11 @@ private function getErrors(FileDefinition $fileDefinition, Importable $import, a
             return [];
         }
 
+        // Globally ignored imports (framework attributes, built-in classes) are always allowed
+        if ($this->isGloballyIgnored($import)) {
+            return [];
+        }
+
         // Check if file is part of some module, if not, no errors
         $moduleOfFile = $this->findModule($fileDefinition);
 
@@ -151,7 +164,7 @@ private function isMarkedAsPublic(Importable $import): bool
         foreach ($this->fileDefinitions as $definition) {
             foreach ($definition->classDefinitions as $classDefinition) {
                 if ($classDefinition->className->isEqual($import)) {
-                    return $this->docReader->isPublic($classDefinition->phpdoc);
+                    return $classDefinition->isExposed;
                 }
             }
         }
@@ -245,6 +258,16 @@ function ($className) {
         return in_array((string)$import, $internalDefinedClasses);
     }
 
+    private function isGloballyIgnored(Importable $import): bool
+    {
+        foreach (self::GLOBAL_IGNORED_NAMESPACES as $ignoredNamespace) {
+            if (NamespaceName::fromString($ignoredNamespace)->isParentOf($import)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     /**
      * @param Reference $dependency
      * @param Module[]|Reference[] $modules

src/Lib/Domain/ClassDefinition.php

@@ -9,7 +9,7 @@ class ClassDefinition
 {
     public bool $isEnum;
 
-    public function __construct(public ClassName $className, public ?string $phpdoc, bool $isEnum = false)
+    public function __construct(public ClassName $className, public bool $isExposed, bool $isEnum = false)
     {
         $this->isEnum = $isEnum;
     }

src/Lib/Errors/Error.php

@@ -2,9 +2,9 @@
 
 namespace PhpModules\Lib\Errors;
 
-/**
- * @public
- */
+use PhpModules\Attributes\Exposed;
+
+#[Exposed]
 abstract class Error
 {
 

src/Lib/Internal/DefinitionsGatherer.php

@@ -6,9 +6,12 @@
 use PhpModules\Lib\Domain\ClassName;
 use PhpModules\Lib\Domain\FileDefinition;
 use PhpModules\Lib\Domain\Importable;
+use PhpModules\Attributes\Exposed;
 use PhpModules\Lib\Domain\NamespaceName;
 use PhpModules\Lib\Modules;
+use PhpParser\Node;
 use PhpParser\NodeTraverser;
+use PhpParser\NodeVisitor\NameResolver;
 use PhpParser\ParserFactory;
 use SplFileInfo;
 
@@ -25,6 +28,7 @@ public function gather(): array
     {
         $parser = (new ParserFactory)->create(ParserFactory::PREFER_PHP7);
         $traverser = new NodeTraverser;
+        $traverser->addVisitor(new NameResolver());
 
         $recursiveIteratorIterator = new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($this->modules->path));
         $regexIterator = new \RegexIterator($recursiveIteratorIterator, '/\.php$/');
@@ -81,7 +85,7 @@ public function gather(): array
                     if ($classStmt->name !== null) {
                         $classDefinition = new ClassDefinition(
                             ClassName::fromNamespaceAndClassName($namespace, $classStmt->name),
-                            $classStmt->getDocComment()?->getText()
+                            $this->hasExposedAttribute($classStmt)
                         );
                         $classDefinitions[] = $classDefinition;
                     }
@@ -91,7 +95,7 @@ public function gather(): array
                     if ($enumStmt->name !== null) {
                         $enumDefinition = new ClassDefinition(
                             ClassName::fromNamespaceAndClassName($namespace, $enumStmt->name),
-                            $enumStmt->getDocComment()?->getText(),
+                            $this->hasExposedAttribute($enumStmt),
                             true
                         );
                         $classDefinitions[] = $enumDefinition;
@@ -126,4 +130,16 @@ private function isIgnored(SplFileInfo $file): bool
         return false;
     }
 
+    private function hasExposedAttribute(Node\Stmt\Class_|Node\Stmt\Enum_ $stmt): bool
+    {
+        foreach ($stmt->attrGroups as $attrGroup) {
+            foreach ($attrGroup->attrs as $attr) {
+                if ($attr->name->toString() === Exposed::class) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+
 }

src/Lib/Module.php

@@ -2,11 +2,10 @@
 
 namespace PhpModules\Lib;
 
+use PhpModules\Attributes\Exposed;
 use PhpModules\Lib\Domain\NamespaceName;
 
-/**
- * @public
- */
+#[Exposed]
 class Module
 {
 

src/Lib/Modules.php

@@ -2,11 +2,10 @@
 
 namespace PhpModules\Lib;
 
+use PhpModules\Attributes\Exposed;
 use PhpModules\Exceptions\PHPModulesException;
 
-/**
- * @public
- */
+#[Exposed]
 class Modules
 {
     /**

src/Lib/Reference.php

@@ -2,15 +2,15 @@
 
 namespace PhpModules\Lib;
 
+use PhpModules\Attributes\Exposed;
 use PhpModules\Lib\Domain\NamespaceName;
 
 /**
- * @public
- *
  * A reference refers to a module that you depend on but don't have access to the full module definition.
  *
  * This is useful when you want to depend on a module that is defined in a different submodule.
  */
+#[Exposed]
 class Reference
 {
 

src/Lib/SubModules.php

@@ -2,9 +2,9 @@
 
 namespace PhpModules\Lib;
 
-/**
- * @public
- */
+use PhpModules\Attributes\Exposed;
+
+#[Exposed]
 class SubModules
 {
 

tests/Lib/Analyzer/AnalyzerTestCase.php

@@ -43,7 +43,7 @@ protected function file(string $namespace, array $classes, array $imports = []):
                 $classDefinitions[] = $class;
             }
             if (is_string($class)) {
-                $classDefinitions[] = new ClassDefinition(ClassName::fromString($class), null);
+                $classDefinitions[] = new ClassDefinition(ClassName::fromString($class), false);
             }
         }
 

tests/Lib/Analyzer/Project/SampleA/SectionA/SectionAModuleA/AAClass.php

@@ -2,11 +2,10 @@
 
 namespace Sample\SectionA\SectionAModuleA;
 
+use PhpModules\Attributes\Exposed;
 use Sample\SectionA\SectionAModuleB\ABClass;
 
-/**
- * @public
- */
+#[Exposed]
 class AAClass
 {
 
@@ -15,4 +14,4 @@ public function get(): ABClass
         return new ABClass();
     }
 
-}
+}

tests/Lib/Analyzer/Project/SampleA/SectionA/SectionAModuleB/ABClass.php

@@ -2,10 +2,10 @@
 
 namespace Sample\SectionA\SectionAModuleB;
 
-/**
- * @public
- */
+use PhpModules\Attributes\Exposed;
+
+#[Exposed]
 class ABClass
 {
 
-}
+}

tests/Lib/Analyzer/Project/SampleA/SectionB/SectionBModuleA/BAClass.php

@@ -2,9 +2,9 @@
 
 namespace Sample\SectionB\SectionBModuleA;
 
-/**
- * @public
- */
+use PhpModules\Attributes\Exposed;
+
+#[Exposed]
 class BAClass
 {
 

tests/Lib/Analyzer/Project/SampleA/SectionB/SectionBModuleB/BBClass.php

@@ -2,11 +2,10 @@
 
 namespace Sample\SectionB\SectionBModuleB;
 
+use PhpModules\Attributes\Exposed;
 use Sample\SectionA\SectionAModuleB\ABClass;
 
-/**
- * @public
- */
+#[Exposed]
 class BBClass
 {
 

tests/Lib/Analyzer/Project/SampleB/SectionA/SectionAModuleA/AAClass.php

@@ -2,11 +2,10 @@
 
 namespace Sample\SectionA\SectionAModuleA;
 
+use PhpModules\Attributes\Exposed;
 use Sample\SectionA\SectionAModuleB\ABClass;
 
-/**
- * @public
- */
+#[Exposed]
 class AAClass
 {