') + ')', 'gi'); if (regex.test(text)) { found = true; var frag = document.createDocumentFragment(); var parts = text.split(regex); parts.forEach(function(part, i) { if (i % 2 === 0) { frag.appendChild(document.createTextNode(part)); } else { var span = document.createElement('span'); span.className = 'userscript-highlight'; span.textContent = part; frag.appendChild(span); } }); node.parentNode.replaceChild(frag, node); } }); } else if (node.nodeType === 1 && node.childNodes) { // element var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT']; if (!skipTags.includes(node.tagName)) { Array.from(node.childNodes).forEach(highlight); } } } highlight(document.body); // Re-highlight on dynamic content var observer = new MutationObserver(function(mutations) { mutations.forEach(function(m) { m.addedNodes.forEach(function(node) { if (node.nodeType === 1 || node.nodeType === 3) highlight(node); }); }); }); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ', 'i'); if (__m === '*' || __re.test(location.href)) { // Strip utm_, fbclid, gclid, etc. from all links on page (function() { var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid', 'ref', 'ref_src', 'source', 'medium', 'campaign']; function cleanUrl(url) { try { var u = new URL(url, window.location.origin); var changed = false; trackingParams.forEach(function(p) { if (u.searchParams.has(p)) { u.searchParams.delete(p); changed = true; } }); return changed ? u.toString() : url; } catch (e) { return url; } } function cleanLinks() { document.querySelectorAll('a[href]').forEach(function(a) { var clean = cleanUrl(a.href); if (clean !== a.href) a.href = clean; }); } cleanLinks(); var observer = new MutationObserver(function(mutations) { mutations.forEach(function(m) { m.addedNodes.forEach(function(node) { if (node.nodeType === 1) { if (node.tagName === 'A') cleanLinks(); node.querySelectorAll('a[href]').forEach(function(a) { var clean = cleanUrl(a.href); if (clean !== a.href) a.href = clean; }); } }); }); }); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); } })(); (function(){ try { var __m = "youtube.com"; var __re = new RegExp('^' + "youtube\\.com" + ', 'i'); if (__m === '*' || __re.test(location.href)) { // Auto-enable theater mode on YouTube (function() { function tryTheater() { var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]'); if (btn && !btn.classList.contains('activated')) { btn.click(); } } // Try immediately tryTheater(); // Try after navigation (SPA) var lastUrl = location.href; setInterval(function() { if (location.href !== lastUrl) { lastUrl = location.href; setTimeout(tryTheater, 500); } }, 1000); // Also try on player load var observer = new MutationObserver(tryTheater); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ', 'i'); if (__m === '*' || __re.test(location.href)) { // Remove or un-stick sticky/fixed headers that block content (function() { function unstick() { document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) { if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') { el.style.position = 'static'; el.style.top = 'auto'; el.style.zIndex = 'auto'; } }); } unstick(); var observer = new MutationObserver(unstick); observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] }); })(); } } catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); } })(); })(); Merge pull request #1 from devitools/copilot/add-main-branch by wilcorrea · Pull Request #2 · devitools/effulgence · GitHub
Skip to content

Merge pull request #1 from devitools/copilot/add-main-branch#2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wilcorrea wants to merge 2 commits into
base:main
Choose a base branch
from
Open

Merge pull request #1 from devitools/copilot/add-main-branch #2

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e646b52
Merge pull request #1 from devitools/copilot/add-main-branch
wilcorrea Feb 14, 2026
844ce24
Update CLAUDE.md to reflect current project state
claude Feb 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
182 changes: 98 additions & 84 deletions CLAUDE.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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) |
Expand All@@ -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

```

@coderabbitaicoderabbitaiBotFeb 14, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language specifier to fenced code block.

The fenced code block is missing a language specifier. While the content is clear, adding a specifier improves consistency with markdown best practices.

📝 Proposed fix
-```+```text
effulgence/

As per coding guidelines, the static analysis tool markdownlint-cli2 flags that fenced code blocks should have a language specified.

🧰 Tools
🪛 markdownlint-cli2 (0.20.0)

[warning] 46-46: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents
In `@CLAUDE.md` at line 46, Update the fenced code block in CLAUDE.md that
currently begins with ``` (containing "effulgence/") to include a language
specifier (e.g., change the opener to ```text or ```plain) so markdownlint-cli2
stops flagging it; locate the lone fenced block in CLAUDE.md and replace the
backticks-only fence with a language-specified fence.

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
Expand All@@ -146,31 +137,42 @@ 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

### 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

Expand All@@ -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:
Expand Down