Qual: Improve AI skills (#39320)
* Qual: Improve AI skills * New: AI skill - common Dolibarr Development # New: AI skill - common Dolibarr Development Added a new SKILL.md file with best practices for Dolibarr development, including database access guidelines, code searching techniques, and tool execution hints (preferring pre-commit).
This commit is contained in:
MDW
GitHub
parent
efa3b42839
commit
cd31a5be33
3 changed files with 210 additions and 50 deletions
|
|
@ -1,6 +1,7 @@
|
|||
---
|
||||
name: add-unit-test
|
||||
description: Add a unit test to test functions or methods.
|
||||
description: >
|
||||
Creates PHP unit tests for Dolibarr ERP/CRM functions and methods. Use when the user asks to add, write, create, or complete a PHPUnit test for Dolibarr, or mentions testing a specific function, method, or class in the Dolibarr codebase.
|
||||
license: MIT
|
||||
user-invocable: true
|
||||
allowed-tools:
|
||||
|
|
@ -8,56 +9,42 @@ allowed-tools:
|
|||
- write_file
|
||||
- grep
|
||||
---
|
||||
|
||||
|
||||
|
||||
# Skill: Add a Unit Test for Dolibarr
|
||||
|
||||
## When to use this skill
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill whenever the user asks to create, modify, or complete a **PHP unit test** for the Dolibarr ERP/CRM project.
|
||||
Use this skill whenever the user asks to create, modify, or complete a PHP unit test for the Dolibarr ERP/CRM project.
|
||||
|
||||
The goal is to produce a unit test that follows Dolibarr conventions and integrates cleanly into the existing PHPUnit test suite.
|
||||
|
||||
|
||||
## Inputs
|
||||
|
||||
The user request should contain, when available:
|
||||
|
||||
- a name of the function to make the unit test for
|
||||
- or the method of the class name to make the unit test for
|
||||
|
||||
- a name of the function to test
|
||||
- or the class method name to test
|
||||
|
||||
## General Rules
|
||||
|
||||
- Follow the coding style already used in files into directory test/phpunit/
|
||||
- Modify the minimum amount of existing code.
|
||||
- Prefer adding new test methods instead of modifying existing ones.
|
||||
- Tests must be deterministic and independent.
|
||||
- Avoid dependencies on external services.
|
||||
- Clean up every object created during the test.
|
||||
- follow the coding style already used in files in the `test/phpunit/` directory
|
||||
- modify the minimum amount of existing code
|
||||
- prefer adding new test methods instead of modifying existing ones
|
||||
- tests must be deterministic and independent
|
||||
- avoid dependencies on external services
|
||||
- clean up every object created during the test
|
||||
|
||||
## Test Location
|
||||
|
||||
Locate the most appropriate existing PHPUnit test file in test/phpunit.
|
||||
|
||||
If no suitable test exists, create one in:
|
||||
|
||||
```
|
||||
test/phpunit/
|
||||
```
|
||||
|
||||
using the naming convention:
|
||||
|
||||
```
|
||||
FeatureTest.php
|
||||
```
|
||||
Locate the most appropriate existing PHPUnit test file in `test/phpunit/`.
|
||||
|
||||
If no suitable test file exists, create one using the naming convention `FeatureTest.php`.
|
||||
|
||||
## Naming
|
||||
|
||||
A test method should describe the expected behavior.
|
||||
|
||||
Examples:
|
||||
**Examples:**
|
||||
|
||||
```php
|
||||
public function testCreateObject()
|
||||
|
|
@ -68,9 +55,9 @@ public function testInvalidInputThrowsException()
|
|||
|
||||
## Assertions
|
||||
|
||||
Prefer specific assertions.
|
||||
Prefer specific assertions over generic ones.
|
||||
|
||||
Good:
|
||||
**Good examples:**
|
||||
|
||||
```php
|
||||
$this->assertTrue($result);
|
||||
|
|
@ -81,9 +68,6 @@ $this->assertNull($value);
|
|||
$this->assertNotNull($value);
|
||||
```
|
||||
|
||||
Avoid generic assertions when a more precise one exists.
|
||||
|
||||
|
||||
## Output
|
||||
|
||||
When generating code:
|
||||
|
|
@ -93,3 +77,41 @@ When generating code:
|
|||
- do not rewrite unrelated methods
|
||||
- explain briefly what is being tested
|
||||
|
||||
## Examples
|
||||
|
||||
### Input: "Add a unit test for the create() method of the Invoice class"
|
||||
|
||||
**Action:**
|
||||
1. locate or create `test/phpunit/InvoiceTest.php`
|
||||
2. add test method following Dolibarr conventions
|
||||
|
||||
### Input: "Write tests for the calculateVAT() function in price.lib.php"
|
||||
|
||||
**Action:**
|
||||
1. locate or create appropriate test file in `test/phpunit/`
|
||||
2. add test methods for various VAT calculation scenarios
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Failures and Validation
|
||||
|
||||
| Issue | Validation | Solution |
|
||||
|-------|------------|----------|
|
||||
| Test file does not exist | Check `test/phpunit/` directory | Create new test file with proper naming |
|
||||
| Class or method not found | Verify namespace and file location | Use proper use statements and class paths |
|
||||
| Database dependencies | Review test for external DB calls | Mock database interactions or use test fixtures |
|
||||
| Non-deterministic behavior | Check for random values or timestamps | Use fixed seeds or mock time |
|
||||
| Missing PHPUnit | Check project dependencies | Ensure PHPUnit is installed via Composer |
|
||||
|
||||
**Before generating code:**
|
||||
- verify the target function or method exists and is accessible
|
||||
- confirm the test directory structure matches Dolibarr conventions
|
||||
- ensure no external service dependencies exist in the code under test
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **Dolibarr global variables**: Tests may need `$conf`, `$db`, `$user` mocks. Use `DolibarrTestCase` if available
|
||||
- **Entity filtering**: Add `entity IN ('.getDolEntity('tablename').')` to SQL in tests if needed
|
||||
- **Permissions**: Some methods check `$user->hasRight()`. Mock user permissions in tests
|
||||
- **File paths**: Use `DOL_DOCUMENT_ROOT` constant for paths, not hardcoded values
|
||||
- **Legacy code**: Older modules may not have test files. Create new ones following current conventions
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
---
|
||||
name: code-review
|
||||
description: Review code and fix bad practices
|
||||
description: >
|
||||
Reviews Dolibarr PHP code for compliance with coding standards and security best practices, and fixes identified issues. Use when the user asks to review, audit, fix, or update code for Dolibarr, or mentions code quality, security vulnerabilities, or PSR-12 compliance.
|
||||
license: MIT
|
||||
user-invocable: true
|
||||
allowed-tools:
|
||||
|
|
@ -8,14 +9,12 @@ allowed-tools:
|
|||
- write_file
|
||||
- grep
|
||||
---
|
||||
|
||||
|
||||
# Skill: Review code for Dolibarr practices and fix it
|
||||
|
||||
## When to use this skill
|
||||
# Skill: Review Dolibarr Code and Fix Bad Practices
|
||||
|
||||
Use this skill whenever the user asks to review code to fix bad practices or to update code to match good practices.
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill whenever the user asks to review, audit, or fix Dolibarr code to match best practices.
|
||||
|
||||
## Inputs
|
||||
|
||||
|
|
@ -25,20 +24,17 @@ The user request should contain, when available:
|
|||
- or a directory name
|
||||
- or a file name
|
||||
|
||||
|
||||
## General Rules
|
||||
|
||||
- Follow the coding style already used in files in module builder template in htdocs/modulebuilder/templates
|
||||
- Modify the minimum amount of existing code.
|
||||
|
||||
- follow the coding style already used in files in the module builder template at `htdocs/modulebuilder/templates`
|
||||
- modify the minimum amount of existing code
|
||||
|
||||
## Rules
|
||||
|
||||
- Use PSR-12 coding style except tabulation that must use TAB characters and not SPACES.
|
||||
- Remove all spaces at end of lines
|
||||
- Rewrite in english all code comments that are not in english
|
||||
- Scan files for security vulnerabilities
|
||||
|
||||
- use PSR-12 coding style except for indentation, which must use TAB characters and not spaces
|
||||
- remove all spaces at the end of lines
|
||||
- rewrite all non-English code comments in English
|
||||
- scan files for security vulnerabilities
|
||||
|
||||
## Output
|
||||
|
||||
|
|
@ -47,5 +43,50 @@ When generating code:
|
|||
- provide only the relevant PHP code
|
||||
- preserve the existing file formatting
|
||||
- do not rewrite unrelated methods
|
||||
- explain briefly what is being tested
|
||||
- explain briefly what is being fixed
|
||||
|
||||
## Examples
|
||||
|
||||
### Input: "Review the supplier invoice module for security issues"
|
||||
|
||||
**Action:**
|
||||
1. scan `htdocs/fournisseur/` directory for common vulnerabilities
|
||||
2. check for unescaped SQL queries
|
||||
3. verify all user inputs use `GETPOST()` with type parameters
|
||||
4. ensure HTML output is escaped with `dolPrintHTML()` or `dolPrintHTMLForAttribute()`
|
||||
|
||||
### Input: "Fix coding style in htdocs/core/lib/functions.lib.php"
|
||||
|
||||
**Action:**
|
||||
1. review file against PSR-12 standards (with TAB exception)
|
||||
2. remove trailing whitespace
|
||||
3. convert non-English comments to English
|
||||
4. apply consistent formatting
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Failures and Validation
|
||||
|
||||
| Issue | Validation | Solution |
|
||||
|-------|------------|----------|
|
||||
| File not found | Verify path exists | Check module structure and file location |
|
||||
| Syntax errors after fix | Run PHP lint | Roll back and reapply changes carefully |
|
||||
| Breaking existing functionality | Run existing tests | Verify tests pass before and after changes |
|
||||
| False positives in security scan | Manual verification | Cross-check with Dolibarr security guidelines |
|
||||
| Mixed line endings | Check with `cat -A` | Normalize to LF |
|
||||
|
||||
**Before applying fixes:**
|
||||
- back up the original file
|
||||
- verify the file is not part of a protected core module
|
||||
- run existing tests to establish a baseline
|
||||
- apply changes incrementally
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **Dolibarr conventions override PSR-12**: Tabs must be used for indentation, not spaces, even though PSR-12 recommends spaces
|
||||
- **Legacy code**: Some older modules cannot be fully PSR-12 compliant. Prioritize consistency with existing module style
|
||||
- **Global variables**: Dolibarr uses globals like `$db`, `$conf`, `$user`. Do not remove these without understanding the architecture
|
||||
- **Dolibarr functions**: Prefer built-in Dolibarr functions (e.g., `dol_print_date()`, `getDolGlobalString()`) over native PHP functions
|
||||
- **SQL injection**: Dolibarr has its own sanitizing and escaping methods (`$db->escape()`, casting to `(int)`, `$db->sanitize()`). Do not replace with prepared statements without testing
|
||||
- **XSS protection**: Use `dolPrintHTML()`, `dolPrintHTMLForAttribute()`, or `dol_htmlentities()` for output, not native `htmlentities()`
|
||||
- **CSRF tokens**: All POST forms must include `<input type="hidden" name="token" value="'.newToken().'">`
|
||||
|
|
|
|||
97
.agents/skills/dolibarr-dev/SKILL.md
Normal file
97
.agents/skills/dolibarr-dev/SKILL.md
Normal file
|
|
@ -0,0 +1,97 @@
|
|||
---
|
||||
name: dolibarr-dev
|
||||
description: Use when developing Dolibarr ERP/CRM code, working with database queries, or asking about Dolibarr best practices.
|
||||
license: MIT
|
||||
user-invocable: true
|
||||
allowed-tools:
|
||||
- read_file
|
||||
- write_file
|
||||
- grep
|
||||
- bash
|
||||
---
|
||||
|
||||
# Dolibarr Development Best Practices
|
||||
|
||||
## When to use this skill
|
||||
|
||||
- When the user asks about Dolibarr coding standards
|
||||
- When reviewing or writing code that interacts with the Dolibarr database
|
||||
- When setting up development environment for Dolibarr
|
||||
- When the user mentions SQL queries, database access, or code searching in Dolibarr
|
||||
|
||||
## Database Access
|
||||
|
||||
### SQL Statements
|
||||
|
||||
**Always use PHP with Dolibarr's database abstraction, never direct SQL CLI.**
|
||||
|
||||
Dolibarr provides database abstraction through the `$db` object. Always use PHP to execute SQL:
|
||||
|
||||
```php
|
||||
// Correct - using Dolibarr's database methods
|
||||
$result = $this->db->query("SELECT * FROM " . $this->db->prefix() . "actioncomm");
|
||||
|
||||
// Wrong - using direct SQL CLI
|
||||
// mysql -e "SELECT * FROM llx_actioncomm"
|
||||
```
|
||||
|
||||
### Table Prefixes
|
||||
|
||||
Use `$this->db->prefix()` instead of the `MAIN_DB_PREFIX` constant:
|
||||
|
||||
```php
|
||||
// Correct:
|
||||
$sql = "SELECT * FROM " . $this->db->prefix() . "actioncomm WHERE id = 1";
|
||||
|
||||
// Legacy (still works but not recommended):
|
||||
$sql = "SELECT * FROM " . MAIN_DB_PREFIX . "actioncomm WHERE id = 1";
|
||||
```
|
||||
|
||||
### Parameter Escaping
|
||||
|
||||
**Integer fields:** Use `(int)` casting
|
||||
**Variable field names:** Use `$this->db->sanitize()`
|
||||
**String fields:** Use `$this->db->escape()`
|
||||
|
||||
```php
|
||||
$sql .= " AND a." . $this->db->sanitize($recurid_field) . " = '" . $this->db->escape($recurid) . "'" AND a.id = " . ((int) $id);
|
||||
```
|
||||
|
||||
(When not in a class, use `$db`)
|
||||
|
||||
|
||||
## Code Searching
|
||||
|
||||
### Use `git grep` for efficiency
|
||||
|
||||
`git grep -n` is more efficient than `grep`:
|
||||
|
||||
```bash
|
||||
# Search in all public facing PHP files
|
||||
git grep -nP 'function NAME\b' -- ":htdocs/*.php"
|
||||
```
|
||||
|
||||
## Quality Assurance
|
||||
|
||||
### Pre-commit Hooks
|
||||
|
||||
When `pre-commit` is installed, use it to run tools (beautifiers, code quality checks):
|
||||
|
||||
```bash
|
||||
if command -v pre-commit >/dev/null 2>&1; then
|
||||
pre-commit run --hook-stage manual shellcheck --file dev/pullmerge.sh
|
||||
fi
|
||||
```
|
||||
|
||||
**Typical Dolibarr pre-commit hooks:**
|
||||
- `phpcs` - PHP Code Sniffer for PSR-12 compliance
|
||||
- `phpcbf` - PHP Code Formatter for PSR-12 compliance
|
||||
- `shellcheck` - Shell script Analysis Tool
|
||||
|
||||
## Coding Standards
|
||||
|
||||
- Follow PSR-12 coding style
|
||||
- Use TAB characters for indentation (not spaces)
|
||||
- Remove all spaces at end of lines
|
||||
- Write all code comments in English, translate existing comments.
|
||||
- Scan files for security vulnerabilities
|
||||
Loading…
Reference in a new issue