Skip to content

Commit 8e69b93

Browse files
Copilotruudk
Copilot
and
ruudk
authored
Add Copilot instructions (#2)
* Initial plan * Initial repository exploration and plan for copilot instructions Co-authored-by: ruudk <104180+ruudk@users.noreply.github.com> * Add comprehensive .github/copilot-instructions.md Co-authored-by: ruudk <104180+ruudk@users.noreply.github.com> * Add composer update warning and revert composer.lock changes Co-authored-by: ruudk <104180+ruudk@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: ruudk <104180+ruudk@users.noreply.github.com>
1 parent dca0447 commit 8e69b93

File tree

1 file changed

+244
-0
lines changed

1 file changed

+244
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
# Copilot Instructions for ruudk/code-generator
2+
3+
## Repository Summary
4+
5+
This is a PHP library that revolutionizes code generation through generators and yield syntax. The `CodeGenerator` class allows developers to yield code line by line while automatically handling indentation, namespace imports, and formatting. Instead of manual string concatenation, developers can write readable generator functions that produce clean, well-formatted PHP code with proper imports and consistent structure.
6+
7+
Key use cases include generating PHP classes, interfaces, enums, traits, and functions with automatic namespace management and beautiful formatting.
8+
9+
## High-Level Repository Information
10+
11+
- **Type**: PHP Composer library/package
12+
- **PHP Version**: Requires PHP 8.4+ (uses property hooks syntax)
13+
- **Size**: Small focused library (~7 source files, ~13 test files)
14+
- **Languages**: PHP only
15+
- **Framework**: Pure PHP with no external runtime dependencies
16+
- **Package Manager**: Composer
17+
- **Target Runtime**: PHP 8.4+ CLI and web environments
18+
- **Namespace**: `Ruudk\CodeGenerator`
19+
20+
## Build and Validation Instructions
21+
22+
**CRITICAL**: This project requires PHP 8.4+. All commands will fail with syntax errors on PHP 8.3 or lower due to property hooks usage.
23+
24+
### Prerequisites
25+
```bash
26+
# Ensure PHP 8.4+ is available
27+
php --version # Must show 8.4+
28+
29+
# Install dependencies
30+
composer install
31+
```
32+
33+
### Important: Composer Dependency Management
34+
35+
**NEVER run `composer update`** unless explicitly requested. This command updates all dependencies to their latest versions and modifies `composer.lock`, which should only be done intentionally by the project maintainer.
36+
37+
- **Use `composer install`** for normal dependency installation - this respects the locked versions
38+
- **Composer modifications** (adding/removing packages) should only be done when explicitly requested
39+
- **Never commit `composer.lock` changes** unless explicitly asked to update dependencies
40+
41+
### Complete Validation Sequence (CI Pipeline Order)
42+
43+
The following commands MUST be run in this exact order. Each command must pass before proceeding:
44+
45+
1. **Validate Composer Configuration**
46+
```bash
47+
composer validate --strict
48+
```
49+
- Takes ~2 seconds
50+
- Validates composer.json syntax and dependencies
51+
52+
2. **Install Dependencies**
53+
```bash
54+
composer install --prefer-dist --no-progress
55+
```
56+
- Takes 30-60 seconds
57+
- ALWAYS run after any composer.json changes
58+
59+
3. **Check Composer Normalization**
60+
```bash
61+
composer normalize --diff --dry-run
62+
```
63+
- Takes ~3 seconds
64+
- Ensures composer.json follows standardized format
65+
66+
4. **Analyze Dependencies**
67+
```bash
68+
vendor/bin/composer-dependency-analyser
69+
```
70+
- Takes ~5 seconds
71+
- Detects unused or missing dependencies
72+
73+
5. **Run Code Style Fixer**
74+
```bash
75+
vendor/bin/php-cs-fixer check --diff
76+
```
77+
- Takes 5-10 seconds
78+
- Validates PSR-12 and custom coding standards
79+
- To fix issues: `vendor/bin/php-cs-fixer fix`
80+
81+
6. **Run Static Analysis**
82+
```bash
83+
vendor/bin/phpstan analyse
84+
```
85+
- Takes 10-15 seconds
86+
- Runs at level 9 (strictest)
87+
- Configuration in phpstan.php
88+
89+
7. **Run Unit Tests**
90+
```bash
91+
vendor/bin/phpunit
92+
```
93+
- Takes 5-10 seconds
94+
- Must have 100% pass rate
95+
- Configuration in phpunit.xml
96+
97+
### Example Validation (Pre-commit Hook)
98+
```bash
99+
# Validate example files (run from project root)
100+
cd examples && for file in *.php; do
101+
echo "Testing examples/$file..."
102+
php "$file" > /dev/null 2>&1 || {
103+
echo "✗ Failed: examples/$file"
104+
exit 1
105+
}
106+
echo "✓ Passed: examples/$file"
107+
done
108+
```
109+
110+
### Development Workflow
111+
112+
1. **Make code changes**
113+
2. **Auto-fix style issues**: `vendor/bin/php-cs-fixer fix`
114+
3. **Run validation sequence** (all commands above)
115+
4. **Test examples** to ensure they work
116+
5. **Commit only if all validations pass**
117+
118+
### Common Issues and Workarounds
119+
120+
- **PHP Version Error**: Project requires PHP 8.4+ due to property hooks syntax. Cannot run on older PHP versions.
121+
- **Memory Issues**: Set `memory_limit=-1` for PHPUnit if needed
122+
- **Lock File Issues**: Run `composer install` before any validation commands
123+
- **Style Failures**: Run `vendor/bin/php-cs-fixer fix` to auto-fix most issues
124+
- **Example Failures**: Examples must execute without errors; they test real library usage
125+
126+
## Project Layout and Architecture
127+
128+
### Core Architecture
129+
130+
The library follows a simple yet powerful architecture:
131+
132+
- **`CodeGenerator`**: Main class for code generation and namespace management
133+
- **`Group`**: Handles indentation and nesting of code blocks
134+
- **`FullyQualified`**: Represents fully qualified class names
135+
- **`ClassName`**: Validates and represents class names
136+
- **`NamespaceName`**: Handles namespace parsing and validation
137+
- **`FunctionName`**: Represents function names for imports
138+
- **`Alias`**: Handles aliased imports
139+
140+
### Directory Structure
141+
142+
```
143+
/
144+
├── .github/
145+
│ ├── workflows/ci.yml # GitHub Actions CI pipeline
146+
│ └── FUNDING.yml # Sponsorship info
147+
├── src/ # Main source code (7 files)
148+
│ ├── CodeGenerator.php # Core generator class
149+
│ ├── Group.php # Indentation/grouping
150+
│ ├── FullyQualified.php # FQCN handling
151+
│ ├── ClassName.php # Class name validation
152+
│ ├── NamespaceName.php # Namespace management
153+
│ ├── FunctionName.php # Function imports
154+
│ └── Alias.php # Import aliases
155+
├── tests/ # Unit tests (matches src structure)
156+
│ ├── CodeGeneratorTest.php # Core functionality tests
157+
│ ├── GroupTest.php # Grouping tests
158+
│ ├── FullyQualifiedTest.php # FQCN tests
159+
│ ├── ClassNameTest.php # Class name tests
160+
│ ├── NamespaceNameTest.php # Namespace tests
161+
│ ├── FunctionNameTest.php # Function tests
162+
│ └── Fixtures/TestEnum.php # Test fixtures
163+
├── examples/ # Working examples
164+
│ ├── example.php # Comprehensive feature demo
165+
│ └── class.php # Simple class generation
166+
├── .php-cs-fixer.php # Code style configuration
167+
├── phpstan.php # Static analysis config
168+
├── phpstan.neon # PHPStan include file
169+
├── phpunit.xml # Test configuration
170+
├── captainhook.json # Git hooks configuration
171+
├── composer-dependency-analyser.php # Dependency analysis config
172+
└── composer.json # Project dependencies
173+
```
174+
175+
### Configuration Files
176+
177+
- **`.php-cs-fixer.php`**: PHP CS Fixer rules using TicketSwap ruleset
178+
- **`phpstan.php`**: PHPStan level 9 with strict rules and custom error formatter
179+
- **`phpunit.xml`**: PHPUnit configuration with strict settings
180+
- **`captainhook.json`**: Pre-commit hooks that run full validation suite
181+
- **`composer-dependency-analyser.php`**: Dependency analysis configuration
182+
183+
### CI/CD Pipeline
184+
185+
GitHub Actions workflow (`.github/workflows/ci.yml`):
186+
- Runs on Ubuntu latest with PHP 8.4
187+
- Matrix strategy for PHP versions
188+
- Caches Composer dependencies
189+
- Executes complete validation sequence
190+
- Must pass for all commits to main branch
191+
192+
### Key Dependencies
193+
194+
**Runtime**: None (pure PHP library)
195+
196+
**Development**:
197+
- `phpunit/phpunit`: Unit testing framework
198+
- `phpstan/phpstan`: Static analysis at level 9
199+
- `friendsofphp/php-cs-fixer`: Code style enforcement
200+
- `captainhook/captainhook-phar`: Git hooks
201+
- `shipmonk/composer-dependency-analyser`: Dependency validation
202+
- `ergebnis/composer-normalize`: Composer.json formatting
203+
204+
### Usage Patterns
205+
206+
The library is designed around generator functions that yield lines of code:
207+
208+
```php
209+
$generator = new CodeGenerator('App\\Services');
210+
211+
echo $generator->dumpFile(function() use ($generator) {
212+
yield 'class UserService';
213+
yield '{';
214+
yield $generator->indent(function() use ($generator) {
215+
yield sprintf('private %s $repository;', $generator->import('App\\Repository\\UserRepository'));
216+
yield '';
217+
yield 'public function find(int $id): ?User';
218+
yield '{';
219+
yield $generator->indent([
220+
'return $this->repository->find($id);'
221+
]);
222+
yield '}';
223+
});
224+
yield '}';
225+
});
226+
```
227+
228+
### File Modification Guidelines
229+
230+
- **Source files** (`src/`): Core library functionality - modify carefully
231+
- **Test files** (`tests/`): Add tests for new features, maintain coverage
232+
- **Examples** (`examples/`): Must remain functional - they're validated in CI
233+
- **Config files**: Changes may affect entire validation pipeline
234+
- **README.md**: Keep examples in sync with actual working code
235+
236+
### Trust These Instructions
237+
238+
These instructions are comprehensive and tested. Only search for additional information if:
239+
- Commands fail with unexpected errors
240+
- New dependencies are added to composer.json
241+
- PHP version requirements change
242+
- CI pipeline is modified
243+
244+
The validation sequence provided is the authoritative build process used by the project maintainer and CI system.

0 commit comments

Comments
 (0)