Merge pull request #35 from tasuku43/issue/26

feat: trait modes, flatten optimization, dumper, CLI flag, docs, tests

Author: tasuku43

ARCHITECTURE.md

@@ -12,29 +12,32 @@
     - Key classes:
       - `ClassDiagram`: Aggregates nodes and relationships; renders Mermaid text.
       - `ClassDiagramBuilder`: Facade to parse and assemble nodes/relationships.
-      - `Node/*`: Type representations (`Class_`, `AbstractClass_`, `Interface_`, `Enum_`) and the common abstract `Node`, plus the `Nodes` collection.
-      - `Node/Relationship/*`: Relationship representations (`Inheritance`, `Realization`, `Composition`, `Dependency`).
+      - `Node/*`: Type representations (`Class_`, `AbstractClass_`, `Interface_`, `Enum_`, `Trait_`) with common abstract `Node`, and the `Nodes` collection.
+      - `Node/Relationship/*`: Relationship representations (`Inheritance`, `Realization`, `Composition`, `Dependency`, `TraitUsage`) and the `Relationships` collection.
       - `Node/Connector/*`: Extract relationship information from the AST and connect `Node`s on `Nodes`.
       - `Node/NodeParser`: Uses Finder to collect files, PHP-Parser to build AST, and Connectors to extract relationships.
+      - `TraitRenderMode`: Rendering strategy for traits (WithTraits or Flatten).
+      - `ClassDiagramDumper`: Debug utility to dump YAML-like structure of nodes/relationships (via reflection).
   - `Console/Command/GenerateCommand.php`: Symfony Console command (`generate --path`).
 - `mermaid-class-diagram`: Executable binary that boots the Console app.
 - `tests/`: PHPUnit tests and fixtures (`tests/data/Project/*`).
 
 ## Domain Model
 ### Nodes (types)
-- `Node` (abstract)
+  - `Node` (abstract)
   - Minimal representation of a type with `$name`.
   - Holds source collections for relationships:
     - `$extends`, `$implements`, `$properties` (composition), `$depends` (dependency)
   - `relationships()`: Builds an array of `Relationship` objects from the above collections.
     - De-duplicates and filters: removes conflicts (e.g., dependency also present as composition/inheritance/realization) and self references.
   - `sortNodes(array &$nodes)`: Sorts by node name (ascending).
 - Concrete types
-  - `Class_`, `AbstractClass_`, `Interface_`, `Enum_`
-  - `render()`: Outputs Mermaid `class` syntax; stereotypes `<<abstract>>`, `<<interface>>`, `<<enum>>` when applicable.
-- `Nodes`
-  - Dictionary-like collection keyed by node name.
-  - Provides `add()`, `findByName()`, `getAllNodes()`.
+  - `Class_`, `AbstractClass_`, `Interface_`, `Enum_`, `Trait_`
+  - `render()`: Outputs Mermaid `class` syntax; stereotypes `<<abstract>>`, `<<interface>>`, `<<enum>>`, `<<trait>>` when applicable.
+  - `Nodes`
+    - Dictionary-like collection keyed by node name.
+    - Provides `add()`, `findByName()`, `getAll()` and `sort()`.
+    - `optimize(RenderOptions $options)`: view-time pruning (e.g., hide trait nodes in Flatten mode). Internally uses a private filter.
 
 ### Relationships
 - `Relationship` (abstract): Holds `from` and `to`; `render()` outputs Mermaid edges.
@@ -53,7 +56,7 @@
   - Input: `--path` may be a directory (glob `*.php`) or a single file (`Symfony\Component\Finder\Finder`).
   - Preparation: Build AST with `PhpParser`; run `NameResolver` and `ParentConnectingVisitor`.
   - Class-like detection:
-    - Gather `Stmt\ClassLike` (Class/Interface/Enum) and also `Stmt\Trait_` nodes, but only Class/Interface/Enum become `Node`s.
+    - Gather `Stmt\ClassLike` (Class/Interface/Enum) and also `Stmt\Trait_` nodes; Class, Interface, Enum, and Trait all become `Node`s.
     - If no valid class-like found in a file, skip via `CannnotParseToClassLikeException`.
   - Two-phase processing:
     - Phase 1: Create `Node` (`Class_`/`AbstractClass_`/`Interface_`/`Enum_`) for each valid class-like and add to `Nodes`.
@@ -72,10 +75,13 @@
     - Method return types of `Name` are dependencies.
     - `new` expressions (`Expr\New_`) add dependencies.
     - Filters out `self` and de-duplicates.
+  - `TraitUsageConnector`
+    - Records `use TraitName;` for class-like nodes (classes and traits).
+    - Enables render-time merging/flattening of trait-derived associations into the using node.
 
 ## Rendering
 - `ClassDiagram::render()`
-  - Sorts nodes by name; sorts relationships by `from to`.
+  - Applies `Nodes::optimize($options)->sort()` and `Relationships::optimize($options)->sort()`.
   - Emits nodes first, then a blank line, then relationships.
   - Header line `classDiagram`; each subsequent line is indented by 4 spaces.
 - Examples
@@ -88,6 +94,30 @@
   - `includeCompositions`: show/hide `Composition` edges (properties/constructor promotion/FQCN properties)
   - `includeInheritances`: show/hide `Inheritance` edges (`extends`)
   - `includeRealizations`: show/hide `Realization` edges (`implements`)
+  - `traitRenderMode` (`TraitRenderMode`): trait rendering policy (default Flatten).
+
+#### Trait rendering modes
+- `WithTraits`:
+  - Show trait nodes and `use` edges.
+  - Keep trait-origin composition/dependency edges attached to the trait.
+  - Suppress duplicate class-level composition/dependency when already provided by a used trait.
+- `Flatten`:
+  - Hide trait nodes and `use` edges.
+  - Reassign trait-origin composition/dependency edges to the using classes.
+  - Transitive flattening: handles trait→trait→class chains (reassign to final class users), with deduplication.
+  - Apply `include*` filters after optimization.
+
+### Relationships optimization
+- `Relationships::optimize(RenderOptions $options)` performs view-time transformations before rendering:
+  - Delegates to private implementations per mode:
+    - `optimizeWithTraitsInternal()`: keep traits/`use`, suppress class-level duplicates for comp/dep.
+    - `optimizeFlattenInternal()`: hide traits/`use`, reassign trait-origin edges to class users (including transitive chains), deduplicate.
+  - Applies include flags via private `filterByOptions()`.
+
+### Debug dumper
+- `ClassDiagramDumper::toYaml(RenderOptions $options = null): string`
+  - Uses reflection to access the diagram’s internals and emits a YAML-like structure for debugging.
+  - Mirrors `render()`’s optimize/sort policy so the dump matches what would be rendered under the same options.
 
 ## CLI
 - Entry: `mermaid-class-diagram`
@@ -104,7 +134,7 @@
   - `symfony/finder` (^7.0): File discovery.
   - `symfony/console` (^7.0): CLI framework.
 - Dev
-  - `phpunit/phpunit` (^9.5): Unit tests.
+  - `phpunit/phpunit`: Unit tests.
 
 ## Notes and Trade-offs
 - Type resolution simplifications
@@ -114,7 +144,9 @@
   - Types referenced but not defined in the scan scope are synthesized as minimal `Node`s so relationships still render.
   - This may produce nodes in the output with empty bodies.
 - Traits
-  - Traits are detected in AST collection but not rendered as nodes; only Class/Interface/Enum are supported.
+  - Participates fully in AST analysis and can be rendered as nodes depending on `TraitRenderMode`.
+  - WithTraits: show trait nodes and `use` edges, suppress duplicate class-level comp/dep provided by traits.
+  - Flatten: hide trait nodes and `use` edges; reassign trait-origin comp/dep to using classes, including transitive trait chains; deduplicate.
 - Safety
   - Never executes target PHP; analysis is static and AST-based.
   - CLI does not currently validate `--path` beyond being required.
@@ -125,6 +157,7 @@
   - Compare `ClassDiagram`/`ClassDiagramBuilder` output against precise expected strings.
 - Fixtures
   - `tests/data/Project/*` provides a small pseudo-app to cover common patterns.
+  - `tests/data/TraitChain/*` covers trait→trait chains and flattening behavior.
 
 ## Extensibility
 - New relationships

README.md

@@ -10,93 +10,59 @@ composer require --dev tasuku43/mermaid-class-diagram
 ```
 
 ## Usage
-Here is an example run on a sample project
-```shell
-$ tree
-.
-├── composer.json
-├── composer.lock
-├── src
-│   ├── SomeAbstractClass.php
-│   ├── SomeClassA.php
-│   ├── SomeClassB.php
-│   ├── SomeClassC.php
-│   ├── SomeClassD.php
-│   ├── SomeClassE.php
-│   └── SomeInterface.php
-└── vendor
-```
-```php
-class SomeClassA extends SomeAbstractClass
-{
-    private SomeClassB $someClassB;
-
-    public function __construct(private SomeClassC $someClassC, SomeClassD $someClassD, private int $int)
-    {
-    }
-}
-
-class SomeClassB
-{
-}
-
-class SomeClassC
-{
-}
-
-class SomeClassD
-{
-}
-
-class SomeClassE
-{
-    public function __construct(private SomeClassA $a)
-    {
-        $b = new SomeClassB;
-    }
-
-    public function dependAandC(SomeClassA $a): SomeClassC
-    {
-    }
-}
 
-abstract class SomeAbstractClass implements SomeInterface
-{
-}
-
-interface SomeInterface
-{
-}
-```
-### Execute command by specifying a directory
+### Command
+- `vendor/bin/mermaid-class-diagram generate --path <path> [options]`
+
+### Options
+- `--path <string>`: Required. Directory (recursively scanned) or single PHP file.
+- `--exclude-relationships <csv>`: Hide edge types; case-insensitive; aliases supported.
+  - `dependency|dependencies|dep|deps`
+  - `composition|compositions|comp`
+  - `inheritance|inheritances|extends`
+  - `realization|realizations|implements`
+- `--trait-mode <mode>`: Trait rendering mode. Default: `flatten`.
+  - `with-traits` (aliases: `with_traits`, `with`): show trait nodes and `use` edges; suppress class-level comp/dep duplicates provided by traits.
+  - `flatten` (aliases: `flat`): hide trait nodes and `use` edges; reassign trait-origin comp/dep to using classes; supports trait→trait→class chains; deduplicates.
+
+### Examples
+#### Execute command by specifying a directory (sample project)
 ```shell
-$ vendor/bin/mermaid-class-diagram generate --path src
+$ vendor/bin/mermaid-class-diagram generate --path tests/data/Project
 classDiagram
-    class SomeAbstractClass {
+    class AbstractController {
         <<abstract>>
     }
-    class SomeClassA {
+    class AuditLogger {
     }
-    class SomeClassB {
+    class AuditTarget {
     }
-    class SomeClassC {
+    class User {
     }
-    class SomeClassD {
+    class UserController {
     }
-    class SomeClassE {
+    class UserRepository {
     }
-    class SomeInterface {
+    class UserRepositoryInterface {
         <<interface>>
     }
+    class UserService {
+    }
+    class UserStatus {
+        <<enum>>
+    }
 
-    SomeInterface <|.. SomeAbstractClass: realization
-    SomeAbstractClass <|-- SomeClassA: inheritance
-    SomeClassA *-- SomeClassB: composition
-    SomeClassA *-- SomeClassC: composition
-    SomeClassA ..> SomeClassD: dependency
-    SomeClassE *-- SomeClassA: composition
-    SomeClassE ..> SomeClassB: dependency
-    SomeClassE ..> SomeClassC: dependency
+    User *-- UserStatus: composition
+    AbstractController <|-- UserController: inheritance
+    UserController *-- UserService: composition
+    UserRepository ..> User: dependency
+    UserRepositoryInterface <|.. UserRepository: realization
+    UserRepositoryInterface ..> User: dependency
+    UserService *-- AuditLogger: composition
+    UserService ..> AuditTarget: dependency
+    UserService ..> InvalidArgumentException: dependency
+    UserService ..> User: dependency
+    UserService *-- UserRepositoryInterface: composition
 ```
 ```mermaid
 classDiagram
@@ -126,17 +92,15 @@ classDiagram
     SomeClassE ..> SomeClassB: dependency
     SomeClassE ..> SomeClassC: dependency
 ```
-### Execute command by specifying a file
+#### Execute command by specifying a file (sample file)
 ```shell
-$ vendor/bin/mermaid-class-diagram generate --path src/SomeClassA.php
+$ vendor/bin/mermaid-class-diagram generate --path tests/data/Project/Controller/UserController.php
 classDiagram
-    class SomeClassA {
+    class UserController {
     }
 
-    SomeAbstractClass <|-- SomeClassA: inheritance
-    SomeClassA *-- SomeClassB: composition
-    SomeClassA *-- SomeClassC: composition
-    SomeClassD <.. SomeClassA: dependency
+    AbstractController <|-- UserController: inheritance
+    UserController *-- UserService: composition
 ```
 ```mermaid
 classDiagram
@@ -149,7 +113,7 @@ classDiagram
     SomeClassD <.. SomeClassA: dependency
 ```
 
-### Filter relationships
+#### Filter relationships
 You can hide specific relationship types via CSV with `--exclude-relationships`.
 
 - Allowed values (case-insensitive, aliases supported):
@@ -167,5 +131,62 @@ $ vendor/bin/mermaid-class-diagram generate --path src --exclude-relationships d
 $ vendor/bin/mermaid-class-diagram generate --path src --exclude-relationships dependency
 ```
 
+#### Traits
+There are two render modes for traits (the CLI uses Flatten by default):
+
+- Flatten (default)
+  - Hides trait nodes and `use` edges.
+  - Reassigns trait-origin composition/dependency edges to the using classes.
+  - Supports transitive trait chains (TraitA uses TraitB); edges are reassigned to the final class users.
+- WithTraits
+  - Shows trait nodes and `use` edges.
+  - Keeps trait-origin composition/dependency edges on the trait.
+  - Suppresses duplicate class-level composition/dependency when already provided by a used trait.
+
+Example
+```php
+trait HasUserDeps {
+    private UserRepository $repo;
+    public function findById(UserId $id): ?User {}
+}
+
+class UserController {
+    use HasUserDeps;
+}
+```
+Output examples (order simplified):
+
+Flatten (default)
+```mermaid
+classDiagram
+    class UserController {
+    }
+    class UserRepository {
+    }
+    class UserId {
+    }
+
+    UserController *-- UserRepository: composition
+    UserController ..> UserId: dependency
+```
+
+WithTraits
+```mermaid
+classDiagram
+    class UserController {
+    }
+    class HasUserDeps {
+        <<trait>>
+    }
+    class UserRepository {
+    }
+    class UserId {
+    }
+
+    UserController --> HasUserDeps: use
+    HasUserDeps *-- UserRepository: composition
+    HasUserDeps ..> UserId: dependency
+```
+
 ## License
 The MIT License (MIT). Please see [LICENSE](https://github.com/tasuku43/php-mermaid-class-diagram/blob/main/LICENSE) for more information.