Adds PHP-Parser based dependency analyzer

Implements a class dependency analyzer using the PHP-Parser library.

This allows for static analysis of PHP code to determine class
dependencies, interfaces, and abstract classes. The implementation
provides an adapter that conforms to the ClassDependenciesParser
interface, enabling a flexible and extensible architecture.

It also adds an AGENTS.md file that explains how agents should operate
within the codebase.

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,52 @@
+<?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();
+        }
+
+        if ($node instanceof Interface_) {
+            $this->fqcn = $node->namespacedName?->toString();
+            $this->isInterface = true;
+        }
+
+        if ($node instanceof Enum_) {
+            $this->fqcn = $node->namespacedName?->toString();
+        }
+
+        if ($node instanceof Node\Name) {
+            $this->dependencies[] = $node->toString();
+        }
+
+        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,
+        );
+    }
+}

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();
+    }
+}