Getting Started

Minimal Setup

Installation:
```
composer require laraveldaily/filacheck --dev
```
Add to composer.json under "require-dev" if not using global install.
First Run:
```
vendor/bin/filacheck
```
Scans app/Filament by default. Exit code 1 indicates issues found.

Quick CI Check: Add to package.json scripts:

"scripts": {
  "filacheck": "vendor/bin/filacheck"
}

Run with:

npm run filacheck

First Use Case: Post-AI Code Review

After generating Filament resources with an AI tool (e.g., GitHub Copilot), run:

vendor/bin/filacheck --dirty

This catches AI-generated deprecated patterns (e.g., reactive() → live()) before manual review.

Implementation Patterns

Daily Workflow Integration

Pre-Commit Hook: Add to .git/hooks/pre-commit:
```
#!/bin/sh
vendor/bin/filacheck --dirty || exit 1
```
Ensures only clean Filament code is committed.

CI Pipeline: Use in GitHub Actions (as shown in README) or Laravel Forge deploy hooks:

- name: Run FilaCheck
  run: vendor/bin/filacheck --detailed
  if: github.event_name == 'pull_request'

Team Onboarding:
- Run vendor/bin/filacheck --dry-run during code reviews to highlight common pitfalls.
- Use --detailed output to explain Filament best practices to junior devs.

Common Patterns

Scenario	Command	Purpose
Scan entire Filament app	`vendor/bin/filacheck`	Catch all deprecated patterns.
Focus on recent changes	`vendor/bin/filacheck --dirty`	Avoid noise in large codebases.
Auto-fix safe issues	`vendor/bin/filacheck --fix`	Apply fixes for `reactive()` → `live()`, `form()` → `schema()`, etc.
Preview fixes	`vendor/bin/filacheck --dry-run`	Review changes before applying.
Custom directory scan	`vendor/bin/filacheck Resources`	Target specific Filament modules (e.g., `Resources`, `Pages`).

Integration Tips

Laravel Forge: Add as a deploy hook to enforce Filament standards.
PHPStorm: Register vendor/bin/filacheck as a "Before Commit" inspection tool.
Laravel Sail: Use --dirty to scan only containerized file changes:
```
sail filacheck --dirty
```
Custom Rules: Extend via config/filacheck.php to disable rules like:
```
'deprecated-reactive' => ['enabled' => false],
```

Gotchas and Tips

Pitfalls

False Positives in Tests:
- The deprecated-test-methods rule may flag legacy test assertions. Exclude test directories:
```
vendor/bin/filacheck --exclude=tests/
```
- Or disable the rule in config/filacheck.php:
```
'deprecated-test-methods' => ['enabled' => false],
```
Auto-Fix Limitations:
- Backup First: Always use --backup with --fix to create .bak files:
```
vendor/bin/filacheck --fix --backup
```
- Non-Fixable Rules: Rules like deprecated-placeholder require manual refactoring.
Path Resolution:
- On Windows, use forward slashes or double backslashes:
```
vendor/bin/filacheck app\\Filament\\Resources
```
- For Sail/Laravel Valet, ensure paths are relative to the project root.
Config Overrides:
- Published config (config/filacheck.php) must be merged with defaults. Use:
```
php artisan vendor:publish --tag=filacheck-config --force
```
- Pro Tip: Disable rules temporarily during migrations:
```
'deprecated-url-parameters' => ['enabled' => false],
```

Debugging

Verbose Output: Use --verbose to see scanned files:
```
vendor/bin/filacheck --verbose
```

Rule-Specific Debugging: Isolate issues with:

vendor/bin/filacheck --rule=deprecated-reactive

Dry-Run with Fixes: Preview all auto-fixable changes:
```
vendor/bin/filacheck --dry-run --fix
```

Extension Points

Custom Rules: Extend the rule set by creating a service provider:

// app/Providers/FilaCheckServiceProvider.php
namespace App\Providers;

use Filacheck\Rules\Rule;
use Illuminate\Support\ServiceProvider;

class FilaCheckServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->extend('filacheck.rules', function ($rules) {
            $rules[] = new class extends Rule {
                public function getName(): string { return 'custom-rule'; }
                public function analyze(string $file): array { /* ... */ }
            });
            return $rules;
        });
    }
}

Rule Configuration: Dynamically enable/disable rules based on Filament version:

// config/filacheck.php
'rules' => [
    'deprecated-reactive' => [
        'enabled' => version_compare(app()->version(), '5.0.0') === -1,
    ],
],

CI-Specific Behavior: Fail builds only on specific rules in CI:

- name: Run FilaCheck (fail on deprecations only)
  run: |
    vendor/bin/filacheck --rule=deprecated-* || true
    vendor/bin/filacheck --rule=best-practice-* || exit 1

Pro Tips

Pair with Laravel Pint: Chain FilaCheck after Pint in CI to enforce both code style and Filament standards:
```
- run: vendor/bin/pint && vendor/bin/filacheck
```
Exclude Vendors: Skip vendor/ and node_modules/ by default in .gitignore-like behavior:
```
vendor/bin/filacheck --exclude=vendor/ --exclude=node_modules/
```

Slack Notifications: Parse FilaCheck output in CI to post warnings to Slack:

- name: Slack Notification
  if: failure()
  run: |
    ISSUES=$(vendor/bin/filacheck --format=json)
    curl -X POST -H 'Content-type: application/json' --data "{\"text\":\"FilaCheck found issues: $ISSUES\"}" $SLACK_WEBHOOK

Filacheck Laravel Package