Peck Laravel Package

Technical Evaluation

Architecture Fit

Peck’s CLI-based, lexicon-focused design integrates seamlessly with Laravel’s developer-centric toolchain (e.g., Artisan, Composer, CI/CD pipelines). It operates at the code readability layer, addressing gaps left by static analyzers (PHPStan) or formatters (Pint) by targeting naming conventions, documentation, and textual consistency. The tool’s reliance on GNU Aspell for spell-checking is a strength, leveraging a battle-tested NLP library, but introduces a system-level dependency that may require additional infrastructure (e.g., Docker, WSL for Windows).

Key Synergies:

• Laravel Preset: Out-of-the-box support for Laravel’s naming conventions (e.g., snake_case for migrations, PascalCase for classes) reduces configuration overhead.
• Composer Integration: Installs as a dev dependency, aligning with Laravel’s modular tooling philosophy (e.g., Pest, Laravel Pint).
• Non-Invasive: Operates on files without modifying them, making it safe for pre-commit hooks or CI gates.

Potential Frictions:

• Laravel-Specific Edge Cases: Custom naming patterns (e.g., domain-specific acronyms, Blade template conventions) may require manual overrides in peck.json.
• Monorepo Challenges: If the codebase spans multiple languages/frameworks, Peck’s PHP-centric focus could limit broader adoption.

Integration Feasibility

Peck’s integration hinges on three pillars:

1. System Dependencies: GNU Aspell must be installed across all environments (dev, CI, staging). This is feasible but introduces cross-platform complexity (e.g., Windows support via WSL/Scoop).
2. Composer Workflow: The tool’s CLI nature allows for pre-commit hooks (via husky/laravel-valet) or CI gates (GitHub Actions, GitLab CI). Example:

   # GitHub Actions
   - name: Run Peck
     run: composer test:typos  # Custom script to invoke ./vendor/bin/peck
   

3. Configuration Overrides: The peck.json preset system enables team-specific rules (e.g., ignoring laravel framework terms or project-specific acronyms).

Feasibility Score:

Technical Risk

Critical Question:

• How will we handle Aspell installation in CI for Windows runners? (Options: WSL, Scoop, or skip Windows CI for Peck checks.)

Key Questions for TPM

1. Adoption Scope:

   • Should Peck be mandatory in CI (blocking PRs) or optional (best-effort)?
   • Which environments (dev, staging, prod) should enforce Peck checks?

2. Configuration Management:

   • Should peck.json be version-controlled or environment-specific?
   • How will we handle team-specific dictionaries (e.g., domain jargon)?

3. Tooling Stack:

   • Will Peck replace or complement existing tools (e.g., PHPStan for naming rules)?
   • Should we integrate Peck with pre-commit hooks (e.g., via laravel-valet)?

4. Long-Term Viability:

   • What’s the upgrade path if Peck reaches v1.0?
   • Should we contribute to Peck’s development (e.g., Laravel-specific rules)?

Integration Approach

Stack Fit

Peck’s integration targets three layers of the Laravel ecosystem:

1. Developer Workflow:

   • Local Development: Add to package.json scripts or .husky/pre-commit:

     "scripts": {
       "check:typos": "php vendor/bin/peck"
     }
     

   • IDE Support: Use as a external tool in PHPStorm/VSCode (run ./vendor/bin/peck manually).

2. CI/CD Pipeline:

   • GitHub Actions: Add to existing workflows (e.g., after composer install):

     - name: Spell Check
       run: composer check:typos
     

   • GitLab CI: Use before_script to install Aspell and run Peck.

3. Laravel-Specific Hooks:

   • Artisan Command: Create a custom command (e.g., php artisan peck) to wrap Peck’s CLI.
   • Service Provider: Register Peck as a console command for Artisan integration.

Migration Path

Rollout Timeline:

• Week 1-2: Pilot in a feature branch.
• Week 3: CI integration (non-blocking).
• Week 4+: Gradual enforcement (e.g., warnings → blocking).

Compatibility

Sequencing

1. Prerequisite: Install GNU Aspell in all environments (dev, CI).
2. Initial Setup:
   • Add Peck to composer.json (--dev).
   • Run ./vendor/bin/peck --init to generate peck.json.
3. Configuration:
   • Apply Laravel preset ("preset": "laravel").
   • Whitelist project-specific terms (e.g., acronyms, frameworkTerms).
4. Testing:
   • Run manually to identify false positives.
   • Adjust peck.json as needed.
5. Automation:
   • Add to CI pipeline (non-blocking initially).
   • Integrate with pre