Clean skeleton (and add Junie guidelines)

.junie/guidelines.md

@@ -0,0 +1,312 @@
+# Project Guidelines for Junie
+
+## Project Overview
+
+Chill is a comprehensive web application built as a set of Symfony bundles. It is a case management system, for social work. The project consists of multiple specialized bundles that provide different functionalities:
+
+- **ChillMainBundle**: Core bundles that provide the foundation of the application
+- **ChillPersonBundle**: Core bundles that provide the foundation of the bundles associated to person (which is the case for all other bundles)
+- **ChillCalendarBundle**: Calendar and scheduling functionality
+- **ChillDocStoreBundle** and **ChillDocGeneratorBundle**: Document management and generation
+- **ChillActivityBundle**, **ChillEventBundle**, **ChillTaskBundle**: Activity and task tracking
+- **ChillBudgetBundle**: Financial management
+- **ChillThirdPartyBundle**: Integration with external systems
+- **ChillCustomFieldsBundle**: Extensibility through custom fields
+- **ChillReportBundle**: Save arbitrary reports about persons
+- **ChillTicketBundle**: Record and track issues about persons
+
+- And several other specialized bundles
+
+## Technology Stack
+
+- **Backend**: PHP 8.3+, Symfony 5.4
+- **Frontend**: JavaScript/TypeScript, Vue.js 3, Bootstrap 5
+- **Build Tools**: Webpack Encore, Yarn
+- **Database**: PostgreSQL with materialized views
+- **Other Services**: Redis, AMQP (RabbitMQ), SMTP
+
+## Project Structure
+
+Note: This is a project which exists from a long time ago, and we found multiple structure inside each bundle. When having the choice, the developers should choose the new structure.
+
+The project follows a standard Symfony bundle structure:
+- `/src/Bundle/`: Contains all the Chill bundles. The code is either at the root of the bundle directory, or within a `src/` directory (preferred). See psr4 mapping at the root's `composer.json`.
+- each bundle come with his own tests, either in the `Tests` directory (when the code is directly within the bundle directory (for instance `src/Bundle/ChillMainBundle/Tests`, `src/Bundle/ChillPersonBundle/Tests`)), or inside the `tests` directory, alongside to the `src/` sub-directory (example: `src/Bundle/ChillWopiBundle/tests`) (this is the preferred way).
+- `/docs/`: Contains project documentation
+
+Each bundle typically has the following structure:
+
+- `Controller/`: Contains controllers
+- `Entity/`: Contains Doctrine entities
+- `Repository/`: Contains Doctrine repositories
+- `Resources/`: Contains views, translations, and public assets
+- `DependencyInjection/`: Contains service configuration
+- `Export/`: Contains services related to exports
+- `Security/`: Contains services related to security. Most of the time, those are new voters, and so on.
+
+### A special word about TicketBundle
+
+The ticket bundle is developed using a kind of "Command" pattern. The controller fill a "Command", and a "CommandHandler" handle this command. They are savec in the `src/Bundle/ChillTicketBundle/src/Action` directory.
+
+## Development Guidelines
+
+### Building and Configuration Instructions
+
+All the command should be run through the `symfony` command, which will configure the required variables.
+
+For assets, we must ensure that we use node at version `^20.0.0`. This is done using `nvm use 20`.
+
+#### Initial Setup
+
+1. **Clone the Repository**:
+   ```bash
+   git clone <repository-url>
+   cd chill-bundles
+   ```
+
+2. **Install PHP Dependencies**:
+   ```bash
+   composer install
+   ```
+
+3. **Install JavaScript Dependencies**:
+   ```bash
+   nvm use 20
+   yarn install
+   ```
+
+4. **Configure Environment Variables**:
+
+   - Create a `.env.local` file with minimal configuration
+   ```bash
+   echo "APP_ENV=dev" >> .env.local
+   ```
+
+5. Start the associated services (database, and so on):
+   ```bash
+   docker compose up -d
+   ```
+
+5. **Set Up the Database**:
+   ```bash
+   # Create the database
+   symfony console doctrine:database:create
+
+   # Run migrations
+   symfony console doctrine:migrations:migrate
+
+   # Load fixtures (optional)
+   symfony console doctrine:fixtures:load
+   ```
+
+6. **Build Assets**:
+   ```bash
+   nvm use 20
+   yarn run encore dev
+   ```
+
+7. **Start the Development Server**:
+   ```bash
+   symfony server:start -d
+   ```
+
+#### Docker Setup
+
+The project includes Docker configuration for easier development:
+
+1. **Start Docker Services**:
+   ```bash
+   docker-compose up -d
+   ```
+
+2. **Access the Application**:
+   - The application will be available at `http://localhost:8000`
+   - PostgreSQL will be available at `localhost:5432`
+   - Redis will be available at `localhost:6379`
+
+#### Building Assets
+
+Before submitting any changes, you should build the project to ensure that all assets are properly compiled:
+
+```bash
+# For production
+yarn run encore production
+
+# For development with hot-reloading
+yarn run encore dev --watch
+
+# for development
+yarn run encore dev
+```
+
+#### Configuration Files
+
+Key configuration files:
+
+- `config/packages/*.yaml`: Symfony bundle configurations
+- `webpack.config.js`: Webpack Encore configuration
+- `composer.json`: PHP dependencies and scripts
+- `package.json`: JavaScript dependencies and scripts
+- `.env`: Default environment variables. Must usually not be updated: use `.env.local` instead.
+
+### Testing Information
+
+The project uses PHPUnit for testing. Each bundle has its own test suite, and there's also a global test suite at the root level.
+
+For creating mock, we prefer using prophecy (library phpspec/prophecy).
+
+#### Running Tests
+
+```bash
+# Run all tests
+vendor/bin/phpunit
+
+# Run tests for a specific bundle
+vendor/bin/phpunit --testsuite NameBundle
+
+# Run a specific test file
+vendor/bin/phpunit path/to/TestFile.php
+
+# Run a specific test method
+vendor/bin/phpunit --filter methodName path/to/TestFile.php
+```
+
+#### Test Structure
+
+Tests are organized by bundle and follow the same structure as the bundle itself:
+
+- Unit tests: Test individual components in isolation
+- Integration tests: Test components working together
+- Functional tests: Test the application from the user's perspective
+
+#### Writing Tests
+
+Tests should be placed in the appropriate bundle's test directory. For example, tests for the TicketBundle should be placed in `src/Bundle/ChillTicketBundle/tests/`.
+
+Here's an example of a simple entity test:
+
+```php
+<?php
+
+namespace Chill\TicketBundle\Tests\Entity;
+
+use Chill\TicketBundle\Entity\Ticket;
+use PHPUnit\Framework\TestCase;
+
+class TicketTest extends TestCase
+{
+    public function testGetAndSetExternalRef(): void
+    {
+        $ticket = new Ticket();
+        $externalRef = 'REF-123';
+
+        // Set the external reference
+        $ticket->setExternalRef($externalRef);
+
+        // Verify that getExternalRef returns the correct value
+        self::assertSame($externalRef, $ticket->getExternalRef());
+
+        // Change the external reference
+        $newExternalRef = 'REF-456';
+        $ticket->setExternalRef($newExternalRef);
+
+        // Verify that getExternalRef returns the updated value
+        self::assertSame($newExternalRef, $ticket->getExternalRef());
+    }
+}
+```
+
+#### Test Database
+
+For tests that require a database, the project uses an in-memory SQLite database by default. You can configure a different database for testing in the `.env.test` file.
+
+### Code Quality Tools
+
+The project uses several tools to maintain code quality:
+
+#### PHP Code Style
+
+The project uses PHP-CS-Fixer for code style. You can run it with:
+
+```bash
+# Using the composer script
+composer php-cs-fixer
+
+# Or directly
+php-cs-fixer fix --config=./.php-cs-fixer.dist.php
+```
+
+#### Static Analysis
+
+The project uses PHPStan for static analysis. You can run it with:
+
+```bash
+# Using the composer script
+composer phpstan
+
+# Or directly
+vendor/bin/phpstan analyse
+```
+
+#### Automated Refactoring
+
+The project uses Rector for automated refactoring. You can run it with:
+
+```bash
+# Using the composer script
+composer rector
+
+# Or directly
+vendor/bin/rector
+```
+
+#### JavaScript/TypeScript Linting
+
+The project uses ESLint for JavaScript/TypeScript code quality. You can run it with:
+
+```bash
+yarn run eslint
+```
+
+## Deployment
+
+The project can be deployed in a production environment following Symfony's deployment guidelines. The documentation provides detailed instructions for setting up a production environment.
+
+### Production Deployment Checklist
+
+1. Set environment variables for production
+2. Optimize Composer autoloader: `composer install --no-dev --optimize-autoloader`
+3. Compile assets for production: `yarn run encore production`
+4. Clear and warm up the cache: `php bin/console cache:clear --env=prod`
+5. Run database migrations: `php bin/console doctrine:migrations:migrate --env=prod`
+
+## Documentation
+
+Comprehensive documentation is available in the `/docs/` directory, including installation instructions, configuration guides, and operational procedures.
+
+## Development Workflow
+
+1. **Create a Feature Branch**: Always create a new branch for your feature or bugfix
+2. **Write Tests**: Write tests for your changes before implementing them
+3. **Implement Changes**: Implement your changes following the project's coding standards
+4. **Run Tests**: Make sure all tests pass
+5. **Run Code Quality Tools**: Make sure your code passes all code quality checks
+6. **Submit a Pull Request**: Submit a pull request for review
+
+## Debugging
+
+The project includes several tools for debugging:
+
+- **Symfony Profiler**: Available in development mode at `/_profiler`
+- **Xdebug**: Configure your IDE to use Xdebug for step-by-step debugging
+- **Symfony Debug Toolbar**: Available at the bottom of the page in development mode
+
+## Conclusion
+
+When working with this project, Junie should:
+
+1. Understand the modular bundle structure and how the different components interact
+2. Build the project before submitting changes to ensure assets are properly compiled
+3. Run relevant tests to ensure changes don't break existing functionality
+4. Follow the established code style and patterns
+5. Use the provided tools for debugging and code quality