From 844ce2498a74012e6f827e19d846c5ff3d6f8dc2 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Feb 2026 03:20:33 +0000 Subject: [PATCH] Update CLAUDE.md to reflect current project state Update repository status, directory structure, testing section, and conventions to accurately describe the implemented 119 source files, 332 tests, and established patterns. https://claude.ai/code/session_01EaKPgUvnXp6zPfzajbzgDF --- CLAUDE.md | 182 +++++++++++++++++++++++++++++------------------------- 1 file changed, 98 insertions(+), 84 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4f7aa1d..a19874a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,53 +25,6 @@ Both projects share: The key difference is that Effulgence leverages Laravel's ecosystem (Eloquent, service providers, middleware, artisan commands, etc.) instead of Hyperf's (annotations, coroutines, config providers). -## Serendipity Reference Architecture - -Use Serendipity's structure as a reference for the capabilities Effulgence should provide, adapted to Laravel idioms: - -``` -serendipity/src/ -├── Domain/ # Pure business logic (framework-agnostic) -│ ├── Collection/ # Type-safe collections -│ ├── Contract/ # Interfaces (Adapter, Support, Testing) -│ │ └── Adapter/ # Serializer/Deserializer contracts -│ ├── Event/ # Domain events -│ ├── Exception/ # Domain exceptions -│ └── Support/ # Domain utilities -├── Infrastructure/ # Technical implementations -│ ├── Adapter/ # Serialize/Deserialize implementations -│ ├── Database/ # Database concerns -│ ├── File/ # File handling -│ ├── Http/ # HTTP client concerns -│ ├── Logging/ # Logging infrastructure -│ └── Repository/ # Repository implementations -│ ├── Repository.php # Base repository -│ ├── PostgresRepository.php -│ ├── MongoRepository.php -│ ├── HttpRepository.php -│ └── SleekDBRepository.php -├── Presentation/ # External interfaces -│ ├── Input/ # Input handling -│ ├── Output/ # Output formatting -│ ├── Input.php # Base input (validation rules) -│ ├── Output.php # Base output -│ └── ReflectorInput.php # Reflection-based input -├── Hyperf/ # **Hyperf-specific bindings** (Effulgence replaces this with Laravel/) -│ ├── Command/ -│ ├── Database/ -│ ├── Event/ -│ ├── Exception/ -│ ├── Listener/ -│ ├── Logging/ -│ ├── Middleware/ -│ ├── Request/ -│ ├── Support/ -│ └── Testing/ -├── Testing/ # Test utilities -├── Example/ # Reference implementations -└── ConfigProvider.php # Hyperf config (Effulgence uses ServiceProvider) -``` - ### Mapping Hyperf concepts to Laravel | Serendipity (Hyperf) | Effulgence (Laravel) | @@ -86,44 +39,82 @@ serendipity/src/ ## Repository Status -This project is in its initial stage. The structure below will evolve as development progresses. +The core implementation is complete with **119 source files** and a comprehensive test suite with **332 tests** and **878 assertions**. The project covers all major DDD layers and Laravel integrations. -## Expected Directory Structure +## Directory Structure ``` effulgence/ ├── src/ -│ ├── Domain/ # Pure business logic (can mirror Serendipity's Domain/) -│ │ ├── Collection/ -│ │ ├── Contract/ -│ │ ├── Event/ -│ │ ├── Exception/ -│ │ └── Support/ -│ ├── Infrastructure/ # Technical implementations -│ │ ├── Adapter/ -│ │ ├── Database/ -│ │ ├── File/ -│ │ ├── Http/ -│ │ ├── Logging/ -│ │ └── Repository/ -│ ├── Presentation/ # Input/Output handling -│ │ ├── Input/ -│ │ └── Output/ -│ ├── Laravel/ # Laravel-specific bindings (replaces Hyperf/) -│ │ ├── Command/ -│ │ ├── Database/ -│ │ ├── Event/ -│ │ ├── Exception/ -│ │ ├── Listener/ -│ │ ├── Logging/ -│ │ ├── Middleware/ -│ │ ├── Request/ -│ │ ├── Support/ -│ │ └── Testing/ -│ ├── Testing/ -│ └── EffulgenceServiceProvider.php -├── config/ +│ ├── Domain/ # Pure business logic (framework-agnostic) +│ │ ├── Collection/ # Type-safe collections (Collection) +│ │ ├── Contract/ # Interfaces +│ │ │ ├── Adapter/ # Serializer/Deserializer contracts +│ │ │ ├── Support/ # ThrownFactory contract +│ │ │ └── Testing/ # Faker, Helper contracts +│ │ ├── Event/ # Domain events (RequestExecuted, ValidationFailed) +│ │ ├── Exception/ # Domain exceptions and parsing +│ │ │ └── Parser/ # Thrown, Additional, DefaultThrownFactory +│ │ └── Support/ # Domain utilities (Task, Truncate) +│ ├── Infrastructure/ # Technical implementations +│ │ ├── Adapter/ # Serialize/Deserialize via Constructo +│ │ │ ├── Deserialize/ # Demolisher +│ │ │ └── Serialize/ # Builder +│ │ ├── Database/ # Database concerns +│ │ │ ├── Document/ # MongoDB/SleekDB (conditions, search, factories) +│ │ │ │ └── Mongo/ # Condition parser, search engine +│ │ │ │ └── Condition/ # Between, Equal, In, Regex conditions +│ │ │ └── Relational/ # Connection, ConnectionChecker, ConnectionFactory +│ │ ├── File/ # File handling (RulesGenerator) +│ │ ├── Http/ # HTTP concerns (JsonFormatter, ExceptionResponseNormalizer) +│ │ ├── Logging/ # StdoutLogger, GoogleCloudLogger, AbstractLogger +│ │ └── Repository/ # Repository implementations +│ │ ├── Adapter/ # Mongo/Relational serializer factories +│ │ ├── Formatter/ # Type-specific formatters (datetime, json, arrays) +│ │ ├── HttpRepository.php # Guzzle-based HTTP repository +│ │ ├── MongoRepository.php # MongoDB repository +│ │ ├── PostgresRepository.php # PostgreSQL repository +│ │ ├── Repository.php # Base repository +│ │ └── SleekDBRepository.php # SleekDB repository +│ ├── Presentation/ # Input/Output handling +│ │ ├── Input/ # Mapped, Params, Resolver +│ │ ├── Output/ # JSend-style response classes +│ │ │ ├── Error/ # 5xx error responses (10 classes) +│ │ │ └── Fail/ # 4xx fail responses (25+ classes) +│ │ ├── Input.php # Base input (validation rules) +│ │ ├── Output.php # Base output +│ │ └── ReflectorInput.php # Reflection-based input +│ ├── Laravel/ # Laravel-specific bindings +│ │ ├── Command/ # Artisan commands (GenerateRules) +│ │ ├── Database/ # Laravel DB implementations +│ │ │ ├── Document/ # LaravelMongoFactory, LaravelSleekDBFactory +│ │ │ └── Relational/ # LaravelConnection, Checker, Factory +│ │ │ └── Support/ # HasPostgresUniqueConstraint +│ │ ├── Event/ # HTTP handle events +│ │ ├── Exception/ # Exception handlers (General, Validation) +│ │ ├── Listener/ # SentryHttpListener +│ │ ├── Logging/ # Logger factories (Stdout, GoogleCloud) +│ │ ├── Middleware/ # CORS, ConnectionChecker, Task, HttpHandler +│ │ ├── Request/ # LaravelFormRequest +│ │ ├── Support/ # Specs, Thrown, Types factories +│ │ └── Testing/ # Test extensions and mocks +│ │ ├── Extension/ # Input, Logger, Make extensions +│ │ ├── Mock/ # Extension mocks +│ │ └── Observability/ # InMemoryLogger for testing +│ ├── Testing/ # Framework-agnostic test utilities +│ │ ├── Extension/ # ResourceExtension +│ │ ├── Mock/ # ResourceExtensionMock +│ │ └── Resource/ # AbstractHelper +│ ├── _/runtime.php # Runtime functions (invoke, dispatch) +│ └── EffulgenceServiceProvider.php # Laravel service provider ├── tests/ +│ ├── Domain/Entity/ # Entity tests +│ ├── Infrastructure/ # Adapter, Database, Exception, Http, Logger, Repository tests +│ ├── Presentation/ # Output tests (Success, Fail, Error parametrized) +│ ├── Laravel/ # Exception, Middleware, Support, Logging, Database tests +│ ├── Testing/ # Test stubs and fixtures +│ ├── _/ # Runtime function tests +│ └── bootstrap.php # Test bootstrap ├── composer.json ├── phpstan.neon ├── phpunit.xml @@ -146,23 +137,34 @@ composer install # Install dependencies composer test # Run tests composer lint # Run static analysis (PHPStan, Psalm, etc.) composer fix # Auto-fix code style +composer ci # Run lint + test ``` ### Testing -- **Framework**: PHPUnit +- **Framework**: PHPUnit 11 +- **Tests**: 332 tests, 878 assertions +- **Skipped**: 3 tests require `ext-mongodb` (annotated with `#[RequiresPhpExtension('mongodb')]`) - Run: `composer test` or `./vendor/bin/phpunit` -- Mirror Serendipity's quality standards: PHPStan, Psalm, PHP CS Fixer, PHPMD, Rector +- Run without coverage: `./vendor/bin/phpunit --no-coverage` +- Test namespace: `Effulgence\Test\` +- Bootstrap: `tests/bootstrap.php` ### Key Dependencies | Package | Purpose | |---|---| | `devitools/constructo` | Metaprogramming foundation (shared with Serendipity) | -| `laravel/framework` | Core framework | +| `laravel/framework` | Core framework (^11.0 or ^12.0) | +| `mongodb/mongodb` | MongoDB driver | +| `guzzlehttp/guzzle` | HTTP client for HttpRepository | +| `mustache/mustache` | Template engine for StdoutLogger | +| `rakibtg/sleekdb` | Flat-file NoSQL database | +| `sentry/sentry-laravel` | Error tracking | | `phpstan/phpstan` | Static analysis | -| `phpunit/phpunit` | Testing | +| `phpunit/phpunit` | Testing (^10.5 or ^11.0) | | `vimeo/psalm` | Type checking | +| `orchestra/testbench` | Laravel package testing | ## Key Conventions @@ -170,7 +172,7 @@ composer fix # Auto-fix code style - PHP 8.3+ with strict types (`declare(strict_types=1)`) - Readonly classes and properties for entities -- Use PHP 8 attributes for metadata (validation rules, serialization hints) +- Use PHP 8 attributes for metadata (validation rules, serialization hints, test requirements) - PSR-4 autoloading under the `Effulgence\` namespace - Follow the same patterns established in Serendipity @@ -181,14 +183,26 @@ composer fix # Auto-fix code style - **Presentation** handles input validation and output formatting - **Laravel/** contains all framework-specific bindings and adapters - Contracts (interfaces) live in `Domain/Contract/`, implementations in `Infrastructure/` +- Runtime functions (`invoke`, `dispatch`) live in `src/_/runtime.php` ### Naming - Namespace: `Effulgence\` +- Test namespace: `Effulgence\Test\` - Service provider: `EffulgenceServiceProvider` - Follow Laravel conventions for artisan commands, middleware, events, etc. - Follow Serendipity conventions for domain concepts (entities, repositories, collections) +### Testing Patterns + +- Tests mirror the `src/` directory structure under `tests/` +- Test stubs and fixtures live in `tests/Testing/Stub/` +- Repository tests use concrete mock classes (e.g., `HttpRepositoryTestMock`) to expose protected methods +- Parametrized tests use PHPUnit `#[DataProvider]` for Success/Fail/Error output classes +- Tests requiring Laravel container set up `Container::getInstance()` with needed bindings in `setUp()` +- Tests requiring facades set up `Facade::setFacadeApplication()` and clean up in `tearDown()` +- MongoDB-dependent tests use `#[RequiresPhpExtension('mongodb')]` to skip gracefully + ## For AI Assistants When working in this repository: