Skip to content

AGENTS.md

Latest commit

 

History

History
82 lines (63 loc) · 3.97 KB

AGENTS.md

File metadata and controls

82 lines (63 loc) · 3.97 KB

Agent Guidelines for Scribe

This repository contains the source code for Scribe, a PHP package that generates API documentation for Laravel applications.

🛠 Project Tooling & Commands

This project uses Composer for dependency management and scripts.

Key Commands

Action Command Description
Run Tests composer test Runs all tests using Pest.
Run Single Test vendor/bin/pest --filter MethodName Runs a specific test method.
Run File Tests vendor/bin/pest path/to/Test.php Runs all tests in a specific file.
Lint Code composer lint Runs PHPStan analysis.
Check Style composer style:check Checks code style without modifying files.
Fix Style composer style:fix Automatically fixes code style issues.

Note: Always run composer test and composer lint before submitting changes.

📐 Code Style & Conventions

Adhere strictly to the existing style. The project generally follows PSR-12.

General PHP

  • Version: PHP 8.1+. Use modern features like typed properties, union types, and constructor promotion where appropriate.
  • Strict Types: Do NOT use declare(strict_types=1); unless strictly necessary or found in the file being edited (it is generally absent).
  • Indentation: 4 spaces.
  • Arrays: Use short array syntax [].
  • Trailing Commas: Use trailing commas in multi-line arrays.

Naming

  • Classes: PascalCase (e.g., PostmanCollectionWriter).
  • Methods: camelCase (e.g., generatePostmanCollection).
  • Variables: camelCase (e.g., $groupedEndpoints).
  • Constants: UPPER_CASE_WITH_UNDERSCORES.

Imports & Namespaces

  • Ordering: Alphabetical order.
  • Grouping: Group standard library imports separately if applicable, but generally keep them sorted.
  • Unused Imports: Remove unused imports.

Type Hinting & Docblocks

  • Types: Use native PHP type hints (param and return types) whenever possible.
    • Example: public function writeDocs(array $groupedEndpoints): void
  • Docblocks:
    • Use PHPDoc for generic arrays to specify content types (e.g., /** @param array<string, mixed> $config */).
    • Use /** @var ClassName $var */ for inline type hinting when the static analyzer cannot infer it (e.g., resolving from container).
    • Do not duplicate native type info in docblocks unless adding detail.

Laravel Integration

  • Dependency Injection: Prefer constructor injection.
  • Helpers: Use Laravel helpers (app(), config(), public_path()) where appropriate and consistent with existing code.
  • Facades: Facades are used (e.g., Storage, Route). Import them via Illuminate\Support\Facades\....

🧪 Testing Guidelines

  • Framework: Tests are written using PHPUnit class syntax (extending BaseLaravelTest or TestCase), but executed via Pest.
  • Location: Place unit tests in tests/Unit/.
  • Naming: Test classes end in Test.php. Test methods use the /** @test */ annotation or start with test.
  • Assertions: Use standard PHPUnit assertions (e.g., $this->assertEquals, $this->assertCount).
  • Mocking: Use Mockery or Laravel's mocking helpers if applicable.

📂 File Structure

  • src/: Core package source code.
    • Writing/: Logic for generating output files (HTML, Postman, OpenAPI).
    • Tools/: Utility classes.
    • Attributes/: PHP Attributes used by the package.
  • tests/: Test suite.
  • resources/views/: Blade templates for generated documentation.
  • config/: Configuration files.

📝 Error Handling

  • Use specific exceptions where possible (e.g., ScribeException).
  • Handle errors gracefully, especially when parsing user code or configuration.
  • Use ConsoleOutputUtils (aliased as c) for CLI output in commands.