Code Commandments

This is a personal tool I built for my own projects. It's public in case others find it useful, but it's tailored to my specific coding standards and workflow.

A Laravel package for enforcing code commandments through prophets who judge and absolve transgressions.

Installation

composer require --dev jessegall/code-commandments

Publish the configuration file:

php artisan vendor:publish --tag=commandments-config

Sacred Terminology

Technical Term	Biblical Term
Violation	Sin / Transgression
Fix/Auto-fix	Repent / Absolution
Warning	Prophecy
Validator	Prophet
Validator class	[Name]Prophet
Validators folder	Prophets/
Pass	Righteous / Blessed
Fail	Sinful / Fallen
Review	Confession
Mark as reviewed	Absolve
Groups	Scrolls

Commands

Judge the Codebase

# Judge all scrolls
php artisan commandments:judge

# Judge a specific scroll
php artisan commandments:judge --scroll=backend

# Judge with a specific prophet
php artisan commandments:judge --prophet=NoRawRequest

# Judge a specific file
php artisan commandments:judge --file=app/Http/Controllers/UserController.php

# Judge multiple specific files (comma-separated)
php artisan commandments:judge --files=app/Models/User.php,app/Services/AuthService.php

# Mark files as absolved after manual review
php artisan commandments:judge --absolve

Seek Absolution (Auto-fix)

# Auto-fix all sins that can be absolved
php artisan commandments:repent

# Preview what would be fixed
php artisan commandments:repent --dry-run

# Fix a specific file
php artisan commandments:repent --file=app/Http/Controllers/UserController.php

# Fix multiple specific files (comma-separated)
php artisan commandments:repent --files=app/Models/User.php,app/Services/AuthService.php

Read the Scripture (List Commandments)

# List all prophets
php artisan commandments:scripture

# List with detailed descriptions
php artisan commandments:scripture --detailed

# List prophets from a specific scroll
php artisan commandments:scripture --scroll=frontend

Summon a New Prophet

# Create a new backend prophet
php artisan make:prophet NoMagicNumbers --scroll=backend

# Create a new frontend prophet
php artisan make:prophet NoInlineStyles --scroll=frontend --type=frontend

# Create a prophet that can auto-fix
php artisan make:prophet NoUnusedImports --repentable

# Create a prophet that requires manual review
php artisan make:prophet ComplexLogicReview --confession

Claude Code Integration

Install hooks to automatically judge your code when using Claude Code:

php artisan commandments:install-hooks

This will:

• Show the scripture (commandments) when starting a Claude Code session
• Run the judge command after Claude completes work
• Distinguish between sins (must fix) and warnings (review and absolve)

Configuration

Configure your scrolls in config/commandments.php:

return [
    'scrolls' => [
        'backend' => [
            'path' => app_path(),
            'extensions' => ['php'],
            'exclude' => ['Console/Kernel.php'],
            'thresholds' => [
                'max_method_lines' => 15,
                'max_private_methods' => 3,  // For ControllerPrivateMethodsProphet
                'min_method_lines' => 3,     // Minimum lines for a method to count
            ],
            'prophets' => [
                \JesseGall\CodeCommandments\Prophets\Backend\NoRawRequestProphet::class,
                // Add more prophets...
            ],
        ],
        'frontend' => [
            'path' => resource_path('js'),
            'extensions' => ['vue', 'ts', 'js'],
            'thresholds' => [
                'max_vue_lines' => 200,
            ],
            'prophets' => [
                \JesseGall\CodeCommandments\Prophets\Frontend\CompositionApiProphet::class,
                // Add more prophets...
            ],
        ],
    ],

    'confession' => [
        'tablet_path' => storage_path('commandments/confessions.json'),
    ],
];

Built-in Prophets

Backend (PHP)

1. NoRawRequestProphet - Thou shalt not access raw request data
2. NoJsonResponseProphet - Thou shalt not return raw JSON responses
3. NoHasMethodInControllerProphet - Thou shalt not use has() in controllers
4. NoEventDispatchProphet - Thou shalt use event() helper for dispatching
5. NoRecordThatOutsideAggregateProphet - Thou shalt not use recordThat() outside aggregates
6. NoValidatedMethodProphet - Thou shalt not use validated() method
7. NoInlineValidationProphet - Thou shalt not use inline validation
8. TypeScriptAttributeProphet - Thou shalt use #[TypeScript] on Resources
9. ReadonlyDataPropertiesProphet - Thou shalt not declare readonly properties in Data class body
10. FormRequestTypedGettersProphet - Thou shalt use typed getters in FormRequest
11. HiddenAttributeProphet - Thou shalt hide sensitive model attributes
12. NoCustomFromModelProphet - Thou shalt not use custom fromModel methods
13. ControllerPrivateMethodsProphet - Thou shalt not have too many private methods in controllers
14. KebabCaseRoutesProphet - Thou shalt use kebab-case for route URIs
15. ConstructorDependencyInjectionProphet - Thou shalt inject dependencies via constructor

Frontend (Vue/TypeScript)

1. NoFetchAxiosProphet - Thou shalt not use fetch() or axios directly
2. TemplateVForProphet - Thou shalt wrap v-for in template elements
3. TemplateVIfProphet - Thou shalt wrap v-if/v-else in template elements
4. RouterHardcodedUrlsProphet - Thou shalt not hardcode URLs in router calls
5. WayfinderRoutesProphet - Thou shalt not hardcode URLs in href attributes
6. CompositionApiProphet - Thou shalt use Composition API
7. ArrowFunctionAssignmentsProphet - Thou shalt use const arrow functions
8. SwitchCaseProphet - Thou shalt not use switch statements
9. LongVueFilesProphet - Thou shalt keep Vue files concise
10. LongTsFilesProphet - Thou shalt keep TypeScript files concise
11. RepeatingPatternsProphet - Thou shalt not repeat template patterns
12. ScriptFirstProphet - Thou shalt put script before template
13. PropsTypeScriptProphet - Thou shalt type props with TypeScript
14. EmitsTypeScriptProphet - Thou shalt type emits with TypeScript
15. InlineEmitTransformProphet - Thou shalt not transform data in emit handlers
16. InlineTypeCastingProphet - Thou shalt not type cast in templates
17. WatchIfPatternProphet - Thou shalt not use watch with if conditions
18. PageDataAccessProphet - Thou shalt use typed page props
19. DeepNestingProphet - Thou shalt not deeply nest template elements
20. StyleOverridesProphet - Thou shalt not override child component styles
21. ExplicitDefaultSlotProphet - Thou shalt use explicit default slots
22. MultipleSlotDefinitionsProphet - Thou shalt type slots with defineSlots
23. ConditionalArrayBuildingProphet - Consider disabled flags pattern for array building
24. SwitchCheckboxVModelProphet - Thou shalt use v-model on Switch/Checkbox
25. LoopsWithIndexedStateProphet - Review indexed state in loops (requires confession)
26. ContentLikePropsProphet - Review content-like props (requires confession)
27. InlineDialogProphet - Review inline dialog definitions (requires confession)

Creating Custom Prophets

<?php

namespace App\Prophets\Backend;

use JesseGall\CodeCommandments\Commandments\PhpCommandment;
use JesseGall\CodeCommandments\Results\Judgment;

class NoMagicNumbersProphet extends PhpCommandment
{
    public function description(): string
    {
        return 'Thou shalt not use magic numbers';
    }

    public function detailedDescription(): string
    {
        return 'Magic numbers should be extracted to named constants...';
    }

    public function judge(string $filePath, string $content): Judgment
    {
        $ast = $this->parse($content);

        if ($ast === null) {
            return $this->skip('Unable to parse PHP file');
        }

        // Your judgment logic here...

        return $this->righteous();
    }
}

Vue/TypeScript Auto-fixing

For Vue and TypeScript auto-fixing, install the Node.js dependencies:

cd vendor/jessegall/code-commandments/node
npm install

Testing

./vendor/bin/phpunit

License

MIT License