Merge pull request #7 from DeGraciaMathieu/php-parser-adapter

Php parser adapter

Author: DeGraciaMathieu

AGENTS.md

@@ -0,0 +1,189 @@
+# AGENTS.md
+
+This file provides guidance for agentic coding assistants operating in this repository.
+Follow these instructions when reading, modifying, or adding code.
+
+---
+
+## Project Overview
+
+- PHP 8.2+ CLI application built with **Laravel Zero**
+- Purpose: analyze PHP class dependencies, coupling, instability, and cycles
+- Architecture: layered (Application / Domain / Infrastructure)
+- Testing: **Pest** (on top of PHPUnit)
+- Formatting: **Laravel Pint**
+
+---
+
+## Environment & Prerequisites
+
+- PHP >= 8.2
+- Composer
+- Xdebug (optional, for coverage)
+
+Install dependencies:
+
+- `composer install`
+
+---
+
+## Build, Lint, and Test Commands
+
+### Running the Application
+
+- Main binary: `class-dependencies-analyzer`
+- Example:
+  - `php class-dependencies-analyzer analyze:class app`
+
+### Tests (Pest)
+
+- Run full test suite:
+  - `composer test`
+  - `vendor/bin/pest -p`
+
+- Run a single test file:
+  - `vendor/bin/pest tests/Unit/FooTest.php`
+
+- Run a single test by name:
+  - `vendor/bin/pest --filter="it does something"`
+
+- Run a specific testsuite:
+  - `vendor/bin/pest --testsuite=Unit`
+
+- Parallel execution is enabled by default via `-p`
+
+### Coverage
+
+- Run tests with coverage:
+  - `composer coverage`
+
+### Linting / Formatting
+
+- Format code using Pint:
+  - `vendor/bin/pint`
+
+- Check formatting without writing:
+  - `vendor/bin/pint --test`
+
+### Healthcheck Scripts
+
+Defined in `composer.json`:
+
+- `composer healthcheck`
+- Includes multiple analyzer self-checks and a test run
+
+---
+
+## Code Style Guidelines
+
+### General
+
+- Follow **PSR-12** and Laravel conventions
+- Prefer clarity over cleverness
+- Keep classes small and single-purpose
+
+### Imports
+
+- Use fully-qualified imports (`use ...`) at top of file
+- One import per line
+- Remove unused imports
+- Group imports logically (PHP, App, Vendor)
+
+### Formatting
+
+- Enforced by **Laravel Pint**
+- 4 spaces indentation
+- One class per file
+- Trailing commas in multiline argument lists
+
+### Naming Conventions
+
+- Classes: `StudlyCase`
+- Methods: `camelCase`
+- Variables: `camelCase`
+- Constants: `SCREAMING_SNAKE_CASE`
+- Interfaces: descriptive nouns (no `Interface` suffix preferred)
+
+### Types & Signatures
+
+- Always use scalar and object type hints
+- Always declare return types
+- Prefer `readonly` and promoted constructor properties where applicable
+- Avoid mixed types unless strictly necessary
+
+### Error Handling
+
+- Use exceptions for exceptional states
+- Catch `Throwable` only at application boundaries
+- Domain logic should not swallow exceptions
+- Present errors via presenters or CLI output, not `echo`
+
+### Null & Defensive Code
+
+- Prefer explicit null checks
+- Avoid deeply nested conditionals
+- Fail fast when input is invalid
+
+---
+
+## Architecture Rules
+
+### Application Layer
+
+- Orchestrates use cases
+- Depends on Domain abstractions (ports)
+- No infrastructure details
+
+### Domain Layer
+
+- Contains core business logic
+- Framework-agnostic
+- No IO, no framework dependencies
+
+### Infrastructure Layer
+
+- Implements ports (filesystem, CLI, adapters)
+- Can depend on frameworks and vendor libraries
+
+### Dependency Direction
+
+- Infrastructure → Application → Domain
+- Never the reverse
+
+---
+
+## Testing Guidelines
+
+- Prefer **Unit tests** for domain logic
+- Use **Feature tests** for CLI commands and integration
+- Tests should be deterministic and isolated
+- Use Mockery for mocking ports
+
+---
+
+## Filesystem & Safety Rules
+
+- Do not modify files in `vendor/`
+- Do not commit generated reports or artifacts
+- Avoid touching unrelated files
+
+---
+
+## Git & Commits
+
+- Do not commit unless explicitly requested
+- Follow existing commit message style
+- Never rewrite history without permission
+
+---
+
+## Agent Behavior Expectations
+
+- Respect this file for all edits in this repository
+- Keep changes minimal and focused
+- Ask before making large refactors
+- Do not introduce new tools or dependencies without approval
+
+---
+
+End of AGENTS.md

app/Infrastructure/Analyze/Adapters/PhpParser/AstClassAnalysis.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace App\Infrastructure\Analyze\Adapters\PhpParser;
+
+use App\Infrastructure\Analyze\Ports\ClassAnalysis;
+
+final class AstClassAnalysis implements ClassAnalysis
+{
+    public function __construct(
+        private readonly string $fqcn,
+        private readonly array $dependencies,
+        private readonly bool $isInterface = false,
+        private readonly bool $isAbstract = false,
+    ) {}
+
+    public function fqcn(): string
+    {
+        return $this->fqcn;
+    }
+
+    public function dependencies(): array
+    {
+        return $this->dependencies;
+    }
+
+    public function isInterface(): bool
+    {
+        return $this->isInterface;
+    }
+
+    public function isAbstract(): bool
+    {
+        return $this->isAbstract;
+    }
+}

app/Infrastructure/Analyze/Adapters/PhpParser/DependencyCollectorVisitor.php

@@ -0,0 +1,65 @@
+<?php
+
+namespace App\Infrastructure\Analyze\Adapters\PhpParser;
+
+use PhpParser\Node;
+use PhpParser\NodeVisitorAbstract;
+use PhpParser\Node\Stmt\Class_;
+use PhpParser\Node\Stmt\Interface_;
+use PhpParser\Node\Stmt\Enum_;
+
+final class DependencyCollectorVisitor extends NodeVisitorAbstract
+{
+    private array $dependencies = [];
+    private ?string $fqcn = null;
+    private bool $isInterface = false;
+    private bool $isAbstract = false;
+
+    public function enterNode(Node $node): void
+    {
+        if ($node instanceof Class_) {
+            $this->fqcn = $node->namespacedName?->toString();
+            $this->isAbstract = $node->isAbstract();
+            $this->isInterface = false;
+        }
+
+        if ($node instanceof Interface_ && $this->fqcn === null) {
+            $this->fqcn = $node->namespacedName?->toString();
+            $this->isInterface = true;
+        }
+
+        if ($node instanceof Enum_) {
+            $this->fqcn = $node->namespacedName?->toString();
+        }
+
+        if ($node instanceof Node\Name) {
+            $name = $node->toString();
+            if (! $this->isBuiltinType($name)) {
+                $this->dependencies[] = $name;
+            }
+        }
+
+        if ($node instanceof Node\Attribute) {
+            $this->dependencies[] = $node->name->toString();
+        }
+    }
+
+    public function analysis(): AstClassAnalysis
+    {
+        return new AstClassAnalysis(
+            fqcn: $this->fqcn ?? '',
+            dependencies: array_values(array_unique($this->dependencies)),
+            isInterface: $this->isInterface,
+            isAbstract: $this->isAbstract,
+        );
+    }
+
+    private function isBuiltinType(string $name): bool
+    {
+        return in_array(strtolower($name), [
+            'string', 'int', 'float', 'bool', 'array', 'callable',
+            'iterable', 'object', 'mixed', 'null', 'false', 'true',
+            'never', 'void', 'self', 'parent', 'static',
+        ], true);
+    }
+}

app/Infrastructure/Analyze/Adapters/PhpParser/PhpAstClassDependenciesParser.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace App\Infrastructure\Analyze\Adapters\PhpParser;
+
+use PhpParser\ParserFactory;
+use PhpParser\NodeTraverser;
+use PhpParser\NodeVisitor\NameResolver;
+use App\Infrastructure\Analyze\Ports\ClassDependenciesParser;
+use App\Infrastructure\Analyze\Ports\ClassAnalysis;
+
+final class PhpAstClassDependenciesParser implements ClassDependenciesParser
+{
+    public function parse(string $file): ClassAnalysis
+    {
+        $code = file_get_contents($file);
+
+        $parser = (new ParserFactory())->createForNewestSupportedVersion();
+        $ast = $parser->parse($code);
+
+        $collector = new DependencyCollectorVisitor();
+
+        $traverser = new NodeTraverser();
+        $traverser->addVisitor(new NameResolver());
+        $traverser->addVisitor($collector);
+        $traverser->traverse($ast);
+
+        return $collector->analysis();
+    }
+}

tests/Fixtures/Php85/ModernClass.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Tests\Fixtures\Php85;
+
+use Attribute;
+use DateTimeInterface;
+use IteratorAggregate;
+
+#[Attribute]
+class CustomAttribute {}
+
+interface Contract {}
+
+abstract class AbstractBase {}
+
+enum Status: string {
+    case Active = 'active';
+}
+
+final class ModernClass extends AbstractBase implements Contract, IteratorAggregate
+{
+    public function __construct(
+        private readonly DateTimeInterface $clock,
+    ) {}
+
+    #[CustomAttribute]
+    public function handle(Status|Contract|null $value): ?DateTimeInterface
+    {
+        return $this->clock;
+    }
+
+    public function getIterator(): \Traversable
+    {
+        return new \ArrayIterator([]);
+    }
+}

tests/Unit/Infrastructure/Analyze/PhpAstClassDependenciesParserTest.php

@@ -0,0 +1,31 @@
+<?php
+
+use App\Infrastructure\Analyze\Adapters\PhpParser\PhpAstClassDependenciesParser;
+
+it('detects dependencies from modern PHP syntax (8.1+) ', function () {
+    $parser = app(PhpAstClassDependenciesParser::class);
+
+    $analysis = $parser->parse(__DIR__ . '/../../../Fixtures/Php85/ModernClass.php');
+
+    expect($analysis->fqcn())->toBe('Tests\\Fixtures\\Php85\\ModernClass');
+
+    expect($analysis->dependencies())->toContain(
+        'Tests\\Fixtures\\Php85\\AbstractBase',
+        'Tests\\Fixtures\\Php85\\Contract',
+        'IteratorAggregate',
+        'DateTimeInterface',
+        'Tests\\Fixtures\\Php85\\Status',
+        'Tests\\Fixtures\\Php85\\CustomAttribute',
+        'ArrayIterator',
+        'Traversable',
+    );
+});
+
+it('marks interface and abstract correctly', function () {
+    $parser = app(PhpAstClassDependenciesParser::class);
+
+    $analysis = $parser->parse(__DIR__ . '/../../../Fixtures/Php85/ModernClass.php');
+
+    expect($analysis->isAbstract())->toBeFalse();
+    expect($analysis->isInterface())->toBeFalse();
+});