Getting Started

Minimal Steps

Install Dependencies: Ensure GNU Aspell is installed system-wide (see README for OS-specific commands).
```
# Example for Ubuntu/Debian
sudo apt-get install aspell aspell-en
```
Add Peck to Laravel: Require the package via Composer and initialize the config:
```
composer require peckphp/peck --dev
./vendor/bin/peck --init
```
This generates peck.json with a Laravel preset (ignores common terms like config, namespace).
First Run: Scan the project for spelling issues:
```
./vendor/bin/peck
```
Use --ignore-all to skip false positives during initial setup:
```
./vendor/bin/peck --ignore-all
```
Integrate into Workflow: Add to composer.json scripts (e.g., test:typos) or CI/CD (see CI section).

Where to Look First

Config File: peck.json (auto-generated via --init). Focus on the ignore.words and ignore.paths arrays to exclude false positives.
Presets: Use preset: "laravel" to skip Laravel-specific terms.
CLI Help: Run ./vendor/bin/peck --help for options like --text (for commit messages) or --path (custom directories).

First Use Case

Scenario: A Laravel project with inconsistent naming (e.g., UserModel vs. User class). Solution:

Run Peck:
```
./vendor/bin/peck
```

Add mismatched names to peck.json under ignore.words:

{
  "preset": "laravel",
  "ignore": {
    "words": ["UserModel", "get_data"]
  }
}

Re-run to verify fixes.

Implementation Patterns

Usage Patterns

1. Local Development Workflow

Pre-commit Hook: Use Husky to run Peck before commits:

# package.json
{
  "scripts": {
    "pre-commit": "peck && git add ."
  }
}

IDE Integration: Use PHPStorm’s "Before Commit" run configuration to trigger Peck.

2. CI/CD Pipeline

GitHub Actions Example:

- name: Spell Check
  run: composer test:typos  # Assumes `test:typos` runs `./vendor/bin/peck`

Fail on Errors: Add --fail-on-error (if supported in future versions) or parse output:
```
if ! ./vendor/bin/peck; then exit 1; fi
```

3. Text-Specific Checks

Commit Messages: Use --text to validate commit messages:

./vendor/bin/peck --text "$(git diff --cached --name-only | head -1)"

Markdown/Blade Docs: Scan documentation files explicitly:
```
./vendor/bin/peck --path resources/views --path docs
```

4. Custom Presets

Extend peck.json for project-specific terms:

{
  "preset": "laravel",
  "ignore": {
    "words": ["AuthServiceProvider", "RouteServiceProvider"],
    "paths": ["config/packages"]
  }
}

Workflows

Onboarding New Developers

Template Setup:
- Include peck.json in your project template with team-specific ignores.
First-Day Check:
- Run Peck during onboarding to highlight naming inconsistencies:
```
./vendor/bin/peck --init && ./vendor/bin/peck
```

Refactoring Legacy Code

Baseline Scan:
- Run Peck to identify all naming issues:
```
./vendor/bin/peck --ignore-all > peck-issues.txt
```
Prioritize Fixes:
- Use ignore.words to temporarily exclude non-critical issues while refactoring.

Documentation Maintenance

Markdown/Blade Checks:

Add a script to composer.json:

{
  "scripts": {
    "docs:check": "peck --path resources/views --path docs"
  }
}

Automate in CI:
- Run composer docs:check in your CI pipeline.

Integration Tips

Laravel-Specific

Artisan Command: Create a custom Artisan command to wrap Peck:

// app/Console/Commands/CheckTypos.php
namespace App\Console\Commands;
use Illuminate\Console\Command;
class CheckTypos extends Command
{
    protected $signature = 'typos:check';
    public function handle()
    {
        $this->call('vendor:publish', ['--provider' => 'Peck\PeckServiceProvider']);
        $this->call('peck');
    }
}

protected $commands = [
    \App\Console\Commands\CheckTypos::class,
];

Pest Tests: Add a Pest test to verify Peck passes:

// tests/Feature/TyposTest.php
it('has no spelling errors', function () {
    $this->artisan('typos:check')
         ->expectsOutputToContain('0 errors')
         ->assertExitCode(0);
});

Symfony Integration

Use symfony/process (already a dependency) to run Peck in Symfony:

use Symfony\Component\Process\Process;
$process = new Process(['./vendor/bin/peck']);
$process->run();
if (!$process->isSuccessful()) {
    throw new \RuntimeException('Peck found typos!');
}

Parallel Execution

For large codebases, split paths across CI jobs:

- name: Peck (App)
  run: ./vendor/bin/peck --path app
- name: Peck (Config)
  run: ./vendor/bin/peck --path config

Gotchas and Tips

Pitfalls

1. GNU Aspell Dependency

Issue: Missing Aspell on CI or local machines.

Fix:

Add Aspell installation to CI (see README).

Document setup in CONTRIBUTING.md:

## Local Setup
Install Aspell:
```bash
# Ubuntu/Debian
sudo apt-get install aspell aspell-en

2. False Positives

Issue: Peck flags valid terms (e.g., config, namespace).
Fix:
- Use the Laravel preset ("preset": "laravel") to ignore common terms.
- Manually add terms to ignore.words in peck.json.

3. Performance

Issue: Slow scans on large codebases.
Fix:
- Exclude paths in ignore.paths (e.g., vendor, node_modules).
- Run in CI with parallel jobs (split by directory).

4. Windows Support

Issue: Aspell is not natively supported on Windows.
Fix:
- Use WSL (Windows Subsystem for Linux) or Scoop:
```
scoop install main/aspell
```
- Document this in README.md under "Windows Setup."

5. Configuration Overrides

Issue: CLI flags override peck.json unexpectedly.
Fix:
- Test with --config to ensure local overrides work:
```
./vendor/bin/peck --config custom/peck.json
```

6. Language Support

Issue: Non-English dictionaries may not be installed.
Fix:
- List available dictionaries in peck.json:
```
{
  "language": "en_GB"  // Example: British English
}
```
- Check installed dictionaries with:
```
aspell dump dicts
```

Debugging

Verbose Output

Enable debug mode (if supported) or check raw Aspell output:
```
./vendor/bin/peck -v  # Hypothetical verbose flag
```

Inspect Aspell’s internal checks:

aspell check en_US < app/Http/Controllers/UserController.php

Ignoring Specific Files

Use ignore.paths to exclude files:

Peck Laravel Package