feat: enable 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 with your own custom guidelines. Match your custom AI guideline path to an existing Boost guideline path, and Boost will install that instead.
+
+For example, to override Inertia React v2 Form Guidance you'd create `.ai/guidelines/inertia-react/2/forms.blade.php`. This file will now be included, instead of Boost's, when you run `boost:install`.
+
 ## 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,7 @@ 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, $key) => $key.($guideline['custom'] ? '*' : ''))->sort()->toArray(), $this->terminal->cols());
         $this->newLine();
         usleep(750000);
 

src/Install/GuidelineComposer.php

@@ -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"))
+        );
     }
 
     /**
@@ -86,7 +92,6 @@ 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,26 @@ protected function guidelinesDir(string $dirPath): ?string
                 ->in($dirPath)
                 ->name('*.blade.php');
         } catch (DirectoryNotFoundException $e) {
-            return null;
+            return [];
         }
 
-        $guidelines = '';
+        $guidelines = [];
         foreach ($finder as $file) {
-            $guidelines .= $this->guideline($file->getRealPath()) ?? '';
-            $guidelines .= PHP_EOL;
+            $guidelines[] = $this->guideline($file->getRealPath());
         }
 
         return $guidelines;
     }
 
-    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 +208,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 +232,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