rspade_system/app/RSpade/CodeQuality/CLAUDE.md

RSpade Code Quality System

Overview

The Code Quality system is a modular, extensible framework for enforcing coding standards and best practices across the RSpade codebase. It replaces a monolithic 1921-line checker with a clean, maintainable architecture using Manifest-based auto-discovery.

Architecture

Core Components

1. CodeQualityChecker (CodeQualityChecker.php)

   • Main orchestrator that discovers and runs all rules
   • Auto-discovers rules via RuleDiscovery::discover_rules()
   • Handles file scanning, caching, and violation collection
   • Performs syntax linting for PHP, JavaScript, and JSON files

2. CodeQualityRule_Abstract (Rules/CodeQualityRule_Abstract.php)

   • Base class for all code quality rules
   • Defines the interface: get_id(), get_name(), check(), etc.
   • Provides add_violation() helper method
   • Rules self-register by extending this class

3. Violation (Violation.php)

   • Data class representing a code violation
   • Contains: rule_id, file_path, line_number, message, severity, code_snippet, suggestion
   • Provides to_array() for serialization

Support Classes

• ViolationCollector - Aggregates violations from all rules
• CacheManager - Caches sanitized file contents to improve performance
• FileSanitizer - Removes comments and strings for accurate code analysis

Rule Categories

PHP Rules (Rules/PHP/)

1. NamingConventionRule (PHP-NAMING-01)

   • Enforces underscore_case for methods and variables
   • Excludes Laravel framework methods (toArray, firstOrCreate, etc.)
   • Severity: Medium

2. MassAssignmentRule (PHP-MASS-01)

   • Prohibits use of $fillable property
   • Ensures $guarded = ['*'] or removal
   • Severity: High

3. PhpFallbackLegacyRule (PHP-FALLBACK-01)

   • Detects "fallback" or "legacy" in comments/function names
   • Enforces fail-loud principle
   • Severity: Critical

4. DbTableUsageRule (PHP-DB-01)

   • Prohibits DB::table() usage
   • Requires ORM models for database access
   • Severity: High

5. FunctionExistsRule (PHP-FUNC-01)

   • Prohibits function_exists() checks
   • Enforces predictable runtime environment
   • Severity: High

Jqhtml Rules (Rules/Jqhtml/)

1. JqhtmlInlineScriptRule (JQHTML-INLINE-01)
   • Prohibits inline <script> and <style> tags in .jqhtml templates
   • Enforces component class pattern with Jqhtml_Component
   • Requires separate .js and .scss files
   • Severity: Critical
   • Runs at manifest-time

JavaScript Rules (Rules/JavaScript/)

1. VarUsageRule (JS-VAR-01)

   • Prohibits 'var' keyword, requires let/const
   • Severity: Medium

2. DefensiveCodingRule (JS-DEFENSIVE-01)

   • Prohibits typeof checks for core classes
   • Core classes always exist in runtime
   • Severity: High

3. InstanceMethodsRule (JS-STATIC-01)

   • Enforces static methods in JavaScript classes
   • Exceptions allowed with @instance-class comment
   • Severity: Medium

4. JQueryUsageRule (JS-JQUERY-01)

   • Enforces $ over jQuery
   • Detects deprecated methods (live, die, bind, etc.)
   • Severity: Medium

5. ThisUsageRule (JS-THIS-01)

   • Detects problematic 'this' usage
   • Suggests class reference pattern
   • Severity: Medium

6. DocumentReadyRule (JS-READY-01)

   • Prohibits jQuery ready patterns
   • Requires ES6 class with static init()
   • Severity: High

7. JsFallbackLegacyRule (JS-FALLBACK-01)

   • JavaScript version of fallback/legacy detection
   • Severity: Critical

Common Rules (Rules/Common/)

1. FilenameCaseRule (FILE-CASE-01)

   • Enforces lowercase filenames
   • Severity: Low

2. FilenameEnhancedRule (FILE-NAME-01)

   • Validates controller/model naming conventions
   • Checks file-class name consistency
   • Severity: Medium

3. RootFilesRule (FILE-ROOT-01)

   • Restricts files in project root
   • Maintains clean project structure
   • Severity: Medium

4. RsxTestFilesRule (FILE-RSX-01)

   • Prevents test files directly in rsx/
   • Enforces proper test organization
   • Severity: Medium

5. RouteExistsRule (ROUTE-EXISTS-01)

   • Validates Rsx::Route() calls reference existing routes
   • Checks controller/method combinations exist in manifest
   • Suggests placeholder URLs for unimplemented routes
   • Severity: High

Sanity Check Rules (Rules/SanityChecks/)

1. PhpSanityCheckRule (PHP-SC-001)
   • Complex pattern detection (currently disabled)
   • Detects suspicious code patterns
   • Severity: Critical

Configuration

Config File (config/rsx.php)

'code_quality' => [
    'enabled' => env('CODE_QUALITY_ENABLED', true),
    'cache_enabled' => true,
    'parallel_processing' => false,
    'excluded_directories' => [
        'vendor',
        'node_modules',
        'storage',
        'bootstrap/cache',
        'CodeQuality', // Exclude checker itself
    ],
    'rsx_test_whitelist' => [
        // Files allowed in rsx/ directory
        'main.php',
        'routes.php',
    ],
],

Disabling Rules

Rules can be disabled by adding them to the disabled list:

'disabled_rules' => [
    'PHP-SC-001', // Temporarily disabled
],

Usage

Command Line

# Run all checks
php artisan rsx:check

# Check specific directory
php artisan rsx:check rsx/

# Check specific file
php artisan rsx:check app/Models/User.php

Exception Comments

Add exception comments to bypass specific violations:

// @RULE-ID-EXCEPTION (e.g., @PHP-NAMING-01-EXCEPTION)
// Code that would normally violate rules

Development

Creating New Rules

1. Create a new class extending CodeQualityRule_Abstract
2. Place in appropriate Rules subdirectory
3. Implement required methods:
   • get_id() - Unique rule identifier
   • get_name() - Human-readable name
   • check() - Violation detection logic
4. Add to Manifest scan directories if needed

Example:

namespace App\RSpade\CodeQuality\Rules\PHP;

use App\RSpade\CodeQuality\Rules\CodeQualityRule_Abstract;

class MyNew_CodeQualityRule extends CodeQualityRule_Abstract
{
    public function get_id(): string
    {
        return 'PHP-NEW-01';
    }

    public function get_name(): string
    {
        return 'My New Rule';
    }

    public function get_description(): string
    {
        return 'Description of what this rule checks';
    }

    public function get_file_patterns(): array
    {
        return ['*.php'];
    }

    /**
     * Whether this rule is called during manifest scan
     *
     * IMPORTANT: This method should ALWAYS return false unless explicitly requested
     * by the framework developer. Manifest-time checks are reserved for critical
     * framework convention violations that need immediate developer attention.
     *
     * Rules executed during manifest scan will run on every file change in development,
     * potentially impacting performance. Only enable this for rules that:
     * - Enforce critical framework conventions that would break the application
     * - Need to provide immediate feedback before code execution
     * - Have been specifically requested to run at manifest-time by framework maintainers
     *
     * DEFAULT: Always return false unless you have explicit permission to do otherwise.
     */
    public function is_called_during_manifest_scan(): bool
    {
        return false; // Always false unless explicitly approved
    }

    public function check(string $file_path, string $contents, array $metadata = []): void
    {
        // Detection logic
        if ($violation_found) {
            $this->add_violation(
                $file_path,
                $line_number,
                "Violation message",
                $code_snippet,
                "How to fix",
                'medium'
            );
        }
    }
}

Testing Rules

1. Create a temporary test file with violations
2. Run php artisan rsx:check
3. Verify violations are detected correctly
4. Clean up test files

Migration from Monolith

The original 1921-line CodeStandardsChecker.php has been:

1. Archived to /archived/CodeStandardsChecker.old.php
2. Split into modular rule classes
3. Enhanced with auto-discovery via Manifest
4. Improved with better caching and performance

All original rule logic has been preserved exactly, ensuring no regression in code quality checks.

Performance

• Caching: Sanitized file contents are cached to avoid repeated processing
• Incremental Linting: Files are only linted if changed since last check
• Efficient Scanning: Smart directory traversal skips excluded paths

Manifest-Time Checking

By default, code quality rules run only when php artisan rsx:check is executed. However, certain critical rules can be configured to run during manifest builds to provide immediate feedback.

When to Enable Manifest-Time Checking

DO NOT enable manifest-time checking unless you have explicit approval. Rules should only run at manifest-time if they:

1. Enforce critical framework conventions that would break the application
2. Need to provide immediate feedback before code execution
3. Have been specifically requested by framework maintainers

Current Manifest-Time Rules

Only the following rules are approved for manifest-time execution:

• BLADE-SCRIPT-01 (InlineScriptRule): Prevents inline JavaScript in Blade files (critical architecture violation)
• JQHTML-INLINE-01 (JqhtmlInlineScriptRule): Prevents inline scripts/styles in Jqhtml template files (critical architecture violation)

All other rules should return false from is_called_during_manifest_scan().

Severity Levels

• Critical: Must fix immediately (e.g., fallback code)
• High: Should fix soon (e.g., mass assignment)
• Medium: Fix when convenient (e.g., naming conventions)
• Low: Minor issues (e.g., filename case)