Merge pull request #219 from laravel/ai-96-allow-guideline-exclusion-overriding

Allow guideline overriding

Author: ashleyhindle

README.md

@@ -97,6 +97,12 @@ Laravel Boost includes AI guidelines for the following packages and frameworks.
 
 To augment Laravel Boost with your own custom AI guidelines, add `.blade.php` files to your application's `.ai/guidelines/*` directory. These files will automatically be included with Laravel Boost's guidelines when you run `boost:install`.
 
+### Overriding Boost AI Guidelines
+
+You can override Boost's built-in AI guidelines by creating your own custom guidelines with matching file paths. When you create a custom guideline that matches an existing Boost guideline path, Boost will use your custom version instead of the built-in one.
+
+For example, to override Boost's "Inertia React v2 Form Guidance" guidelines, create a file at `.ai/guidelines/inertia-react/2/forms.blade.php`. When you run `boost:install`, Boost will include your custom guideline instead of the default one.
+
 ## Manually Registering the Boost MCP Server
 
 Sometimes you may need to manually register the Laravel Boost MCP server with your editor of choice. You should register the MCP server using the following details:

src/Console/InstallCommand.php

@@ -390,7 +390,14 @@ private function installGuidelines(): void
 
         $this->newLine();
         $this->info(sprintf(' Adding %d guidelines to your selected agents', $guidelines->count()));
-        DisplayHelper::grid($guidelines->keys()->sort()->toArray(), $this->terminal->cols());
+        DisplayHelper::grid(
+            $guidelines
+                ->map(fn ($guideline, string $key) => $key.($guideline['custom'] ? '*' : ''))
+                ->values()
+                ->sort()
+                ->toArray(),
+            $this->terminal->cols()
+        );
         $this->newLine();
         usleep(750000);
 

src/Install/GuidelineComposer.php

@@ -14,7 +14,7 @@ class GuidelineComposer
 {
     protected string $userGuidelineDir = '.ai/guidelines';
 
-    /** @var Collection<string, string> */
+    /** @var Collection<string, array> */
     protected Collection $guidelines;
 
     protected GuidelineConfig $config;
@@ -42,18 +42,24 @@ public function compose(): string
         return self::composeGuidelines($this->guidelines());
     }
 
+    public function customGuidelinePath(string $path = ''): string
+    {
+        return base_path($this->userGuidelineDir.'/'.ltrim($path, '/'));
+    }
+
     /**
      * Static method to compose guidelines from a collection.
      * Can be used without Laravel dependencies.
      *
-     * @param Collection<string, string> $guidelines
+     * @param Collection<string, array{content: string, name: string, path: ?string, custom: bool}> $guidelines
      */
     public static function composeGuidelines(Collection $guidelines): string
     {
         return str_replace("\n\n\n\n", "\n\n", trim($guidelines
-            ->filter(fn ($content) => ! empty(trim($content)))
-            ->map(fn ($content, $key) => "\n=== {$key} rules ===\n\n".trim($content))
-            ->join("\n\n")));
+            ->filter(fn ($guideline) => ! empty(trim($guideline['content'])))
+            ->map(fn ($guideline, $key) => "\n=== {$key} rules ===\n\n".trim($guideline['content']))
+            ->join("\n\n"))
+        );
     }
 
     /**
@@ -65,7 +71,7 @@ public function used(): array
     }
 
     /**
-     * @return Collection<string, string>
+     * @return Collection<string, array>
      */
     public function guidelines(): Collection
     {
@@ -79,14 +85,13 @@ public function guidelines(): Collection
     /**
      * Key is the 'guideline key' and value is the rendered blade.
      *
-     * @return \Illuminate\Support\Collection<string, string>
+     * @return \Illuminate\Support\Collection<string, array>
      */
     protected function find(): Collection
     {
         $guidelines = collect();
         $guidelines->put('foundation', $this->guideline('foundation'));
         $guidelines->put('boost', $this->guideline('boost/core'));
-
         $guidelines->put('php', $this->guideline('php/core'));
 
         // TODO: AI-48: Use composer target version, not PHP version. Production could be 8.1, but local is 8.4
@@ -119,49 +124,39 @@ protected function find(): Collection
                 $guidelineDir.'/core',
                 $this->guideline($guidelineDir.'/core')
             ); // Always add package core
-
-            $guidelines->put(
-                $guidelineDir.'/v'.$package->majorVersion(),
-                $this->guidelinesDir($guidelineDir.'/'.$package->majorVersion())
-            );
+            $packageGuidelines = $this->guidelinesDir($guidelineDir.'/'.$package->majorVersion());
+            foreach ($packageGuidelines as $guideline) {
+                $suffix = $guideline['name'] == 'core' ? '' : '/'.$guideline['name'];
+                $guidelines->put(
+                    $guidelineDir.'/v'.$package->majorVersion().$suffix,
+                    $guideline
+                );
+            }
         }
 
         if ($this->config->enforceTests) {
             $guidelines->put('tests', $this->guideline('enforce-tests'));
         }
 
-        $userGuidelines = $this->guidelineFilesInDir(base_path($this->userGuidelineDir));
+        $userGuidelines = $this->guidelinesDir($this->customGuidelinePath());
+        $pathsUsed = $guidelines->pluck('path');
 
         foreach ($userGuidelines as $guideline) {
-            $guidelineKey = '.ai/'.$guideline->getBasename('.blade.php');
-            $guidelines->put($guidelineKey, $this->guideline($guideline->getPathname()));
+            if ($pathsUsed->contains($guideline['path'])) {
+                continue; // Don't include this twice if it's an override
+            }
+            $guidelines->put('.ai/'.$guideline['name'], $guideline);
         }
 
         return $guidelines
-            ->whereNotNull()
-            ->where(fn (string $guideline) => ! empty(trim($guideline)));
+            ->where(fn (array $guideline) => ! empty(trim($guideline['content'])));
     }
 
     /**
-     * @return Collection<string, \Symfony\Component\Finder\SplFileInfo>
+     * @param string $dirPath
+     * @return array<array{content: string, name: string, path: ?string, custom: bool}>
      */
-    protected function guidelineFilesInDir(string $dirPath): Collection
-    {
-        if (! is_dir($dirPath)) {
-            $dirPath = str_replace('/', DIRECTORY_SEPARATOR, __DIR__.'/../../.ai/'.$dirPath);
-        }
-
-        try {
-            return collect(iterator_to_array(Finder::create()
-                ->files()
-                ->in($dirPath)
-                ->name('*.blade.php')));
-        } catch (DirectoryNotFoundException $e) {
-            return collect();
-        }
-    }
-
-    protected function guidelinesDir(string $dirPath): ?string
+    protected function guidelinesDir(string $dirPath): array
     {
         if (! is_dir($dirPath)) {
             $dirPath = str_replace('/', DIRECTORY_SEPARATOR, __DIR__.'/../../.ai/'.$dirPath);
@@ -173,27 +168,21 @@ protected function guidelinesDir(string $dirPath): ?string
                 ->in($dirPath)
                 ->name('*.blade.php');
         } catch (DirectoryNotFoundException $e) {
-            return null;
+            return [];
         }
 
-        $guidelines = '';
-        foreach ($finder as $file) {
-            $guidelines .= $this->guideline($file->getRealPath()) ?? '';
-            $guidelines .= PHP_EOL;
-        }
-
-        return $guidelines;
+        return array_map(fn ($file) => $this->guideline($file->getRealPath()), iterator_to_array($finder));
     }
 
-    protected function guideline(string $path): ?string
+    /**
+     * @param string $path
+     * @return array{content: string, name: string, path: ?string, custom: bool}
+     */
+    protected function guideline(string $path): array
     {
-        if (! file_exists($path)) {
-            $path = preg_replace('/\.blade\.php$/', '', $path);
-            $path = str_replace('/', DIRECTORY_SEPARATOR, __DIR__.'/../../.ai/'.$path.'.blade.php');
-        }
-
-        if (! file_exists($path)) {
-            return null;
+        $path = $this->guidelinePath($path);
+        if (is_null($path)) {
+            return ['content' => '', 'name' => '', 'path' => null, 'custom' => false];
         }
 
         $content = file_get_contents($path);
@@ -214,7 +203,12 @@ protected function guideline(string $path): ?string
         $rendered = str_replace(array_keys($this->storedSnippets), array_values($this->storedSnippets), $rendered);
         $this->storedSnippets = []; // Clear for next use
 
-        return trim($rendered);
+        return [
+            'content' => trim($rendered),
+            'name' => str_replace('.blade.php', '', basename($path)),
+            'path' => $path,
+            'custom' => str_contains($path, $this->customGuidelinePath()),
+        ];
     }
 
     private array $storedSnippets = [];
@@ -233,4 +227,44 @@ private function processBoostSnippets(string $content): string
             return $placeholder;
         }, $content);
     }
+
+    protected function prependPackageGuidelinePath(string $path): string
+    {
+        $path = preg_replace('/\.blade\.php$/', '', $path);
+        $path = str_replace('/', DIRECTORY_SEPARATOR, __DIR__.'/../../.ai/'.$path.'.blade.php');
+
+        return $path;
+    }
+
+    protected function prependUserGuidelinePath(string $path): string
+    {
+        $path = preg_replace('/\.blade\.php$/', '', $path);
+        $path = str_replace('/', DIRECTORY_SEPARATOR, $this->customGuidelinePath($path.'.blade.php'));
+
+        return $path;
+    }
+
+    protected function guidelinePath(string $path): ?string
+    {
+        // Relative path, prepend our package path to it
+        if (! file_exists($path)) {
+            $path = $this->prependPackageGuidelinePath($path);
+            if (! file_exists($path)) {
+                return null;
+            }
+        }
+
+        $path = realpath($path);
+
+        // If this is a custom guideline, return it unchanged
+        if (str_contains($path, $this->customGuidelinePath())) {
+            return $path;
+        }
+
+        // The path is not a custom guideline, check if the user has an override for this
+        $relativePath = ltrim(str_replace([realpath(__DIR__.'/../../'), '.ai/'], '', $path), '/');
+        $customPath = $this->prependUserGuidelinePath($relativePath);
+
+        return file_exists($customPath) ? $customPath : $path;
+    }
 }

tests/Feature/Install/GuidelineComposerTest.php

@@ -206,9 +206,9 @@
 
     expect($guidelines)
         ->toContain('=== inertia-react/core rules ===')
-        ->toContain('=== inertia-react/v2 rules ===')
+        ->toContain('=== inertia-react/v2/forms rules ===')
         ->toContain('=== inertia-vue/core rules ===')
-        ->toContain('=== inertia-vue/v2 rules ===')
+        ->toContain('=== inertia-vue/v2/forms rules ===')
         ->toContain('=== pest/core rules ===');
 });
 
@@ -251,3 +251,50 @@
         ->toContain('laravel/v11')
         ->toContain('pest/core');
 });
+
+test('includes user custom guidelines from .ai/guidelines directory', function () {
+    $packages = new PackageCollection([
+        new Package(Packages::LARAVEL, 'laravel/framework', '11.0.0'),
+    ]);
+
+    $this->roster->shouldReceive('packages')->andReturn($packages);
+
+    $composer = Mockery::mock(GuidelineComposer::class, [$this->roster, $this->herd])->makePartial();
+    $composer
+        ->shouldReceive('customGuidelinePath')
+        ->andReturnUsing(fn ($path = '') => realpath(\Pest\testDirectory('fixtures/.ai/guidelines')).'/'.ltrim($path, '/'));
+
+    expect($composer->compose())
+        ->toContain('=== .ai/custom-rule rules ===')
+        ->toContain('=== .ai/project-specific rules ===')
+        ->toContain('This is a custom project-specific guideline')
+        ->toContain('Project-specific coding standards')
+        ->toContain('Database tables must use `snake_case` naming')
+        ->and($composer->used())
+        ->toContain('.ai/custom-rule')
+        ->toContain('.ai/project-specific');
+});
+
+test('non-empty custom guidelines override Boost guidelines', function () {
+    $packages = new PackageCollection([
+        new Package(Packages::LARAVEL, 'laravel/framework', '11.0.0'),
+    ]);
+
+    $this->roster->shouldReceive('packages')->andReturn($packages);
+
+    $composer = Mockery::mock(GuidelineComposer::class, [$this->roster, $this->herd])->makePartial();
+    $composer
+        ->shouldReceive('customGuidelinePath')
+        ->andReturnUsing(fn ($path = '') => realpath(\Pest\testDirectory('fixtures/.ai/guidelines')).'/'.ltrim($path, '/'));
+
+    $guidelines = $composer->compose();
+    $overrideStringCount = substr_count($guidelines, 'Thanks though, appreciate you');
+
+    expect($overrideStringCount)->toBe(1)
+        ->and($guidelines)
+        ->toContain('Thanks though, appreciate you') // From user guidelines
+        ->not->toContain('## Laravel 11') // Heading from Boost's L11/core guideline
+        ->and($composer->used())
+        ->toContain('.ai/custom-rule')
+        ->toContain('.ai/project-specific');
+});

tests/Unit/Install/GuidelineComposerTest.php

@@ -0,0 +1,5 @@
+This is a custom project-specific guideline.
+
+Use the following conventions:
+- Always prefix custom classes with `Project`
+- Use camelCase for method names

tests/fixtures/.ai/guidelines/custom-rule.blade.php

@@ -0,0 +1,3 @@
+I don't want your guidelines, I've got my own, and they're great.
+
+Thanks though, appreciate you!

tests/fixtures/.ai/guidelines/laravel/11/core.blade.php

@@ -0,0 +1,5 @@
+Project-specific coding standards:
+
+- Database tables must use `snake_case` naming
+- All controllers should extend `BaseController`
+- Use the `@assist->package('laravel')` helper when available