rspade_system/app/RSpade/CodeQuality/Rules/.expect_documentation_summary.md

Code Quality Rule Expectations - Group 8 Documentation

Summary

Created comprehensive .expect files for all 31 code quality rules in:

• Blade/ directory (6 rules)
• Common/ directory (20 rules)
• Convention/ directory (5 rules)

Created: 2025-12-24

File Structure

Each .expect file documents:

• Detection: What patterns trigger violations
• Context: Scope, affected files, exclusions
• Violation Details: Rule ID, severity, message
• Remediation: How to fix violations
• Convention Explanation: Why the rule exists

Blade Rules (6 files)

Rule	File	Purpose
BLADE-EXTENDS-01	BladeExtends_CodeQualityRule.php.expect	Correct @extends syntax
BLADE-RSX-FQCN-01	BladeFqcnUsage_CodeQualityRule.php.expect	Avoid FQCN references
BLADE-EVENT-01	InlineEventHandler_CodeQualityRule.php.expect	Prevent inline event handlers
BLADE-SCRIPT-01	InlineScript_CodeQualityRule.php.expect	Prevent inline <script> tags
BLADE-LAYOUT-ASSETS-01	LayoutLocalAssets_CodeQualityRule.php.expect	Use bundle system for assets
BLADE-TAGS-01	UnbalancedTags_CodeQualityRule.php.expect	Keep HTML tags balanced

Common Rules (20 files)

Rule	File	Purpose
ABSTRACT-CLASS-01	AbstractClassNaming_CodeQualityRule.php.expect	Abstract class naming
COMMON-ASSIGN-01	Assignment_Comparison_CodeQualityRule.php.expect	Assignment vs comparison
CMD-ORG-01	CommandOrganization_CodeQualityRule.php.expect	Command directory organization
FILE-CASE-01	FilenameCase_CodeQualityRule.php.expect	Lowercase filenames in rsx/
FILE-ENHANCED-01	FilenameEnhanced_CodeQualityRule.php.expect	No 'enhanced' suffix
FILE-SPACE-01	FilenameSpaces_CodeQualityRule.php.expect	No spaces in filenames
MANIFEST-PRIORITY-01	ManifestModulePriority_CodeQualityRule.php.expect	Module priority ordering
FILE-OLD-01	OldFiles_CodeQualityRule.php.expect	Old file patterns
PKG-JSON-01	PackageJson_CodeQualityRule.php.expect	Dependencies only
ROUTE-INDEX-01	RedundantIndexAction_CodeQualityRule.php.expect	Avoid redundant 'index'
DIR-RESOURCE-01	ResourceDirectory_CodeQualityRule.php.expect	Use singular 'resource'
FILE-ROOT-01	RootFiles_CodeQualityRule.php.expect	No test files in root
ROUTE-SYNTAX-01	RouteSyntax_CodeQualityRule.php.expect	Use :param syntax
RSX-CMD-DEPRECATED-01	RsxCommandsDeprecated_CodeQualityRule.php.expect	No deprecated references
FILE-RSX-01	RsxTestFiles_CodeQualityRule.php.expect	Test files in proper directories
FILE-TEMP-01	TempFiles_CodeQualityRule.php.expect	No -temp files
FILE-SUBCLASS-01	SubclassNaming_CodeQualityRule.php.expect	Subclass suffix matching
ROUTE-EXISTS-01	RouteExists_CodeQualityRule.php.expect	Route validation
FILE-CASE-DUP-01	DuplicateCaseFiles_CodeQualityRule.php.expect	No case-insensitive duplicates
URL-HARDCODE-01	HardcodedInternalUrl_CodeQualityRule.php.expect	Use route generation

Convention Rules (5 files)

Rule	File	Purpose
CONV-BUNDLE-02	BundleIncludePath_CodeQualityRule.php.expect	Bundles include own directory
CONV-BUNDLE-01	BundleLocation_CodeQualityRule.php.expect	Bundle location convention
CONV-LAYOUT-01	LayoutLocation_CodeQualityRule.php.expect	Layout file location
CONV-FILENAME-01	FilenameRedundantPrefix_CodeQualityRule.php.expect	Filename clarity convention
CONV-BUNDLE-03	OneBundlePerModule_CodeQualityRule.php.expect	One bundle per module

Documentation Format

Each .expect file follows this standard structure:

# {Filename}.expect
# Created: 2025-12-24

## Detection

EXPECT: {What violation this rule detects}
GIVEN: {Code pattern that triggers violation}
WHEN: {Condition for detection}
THEN: {Result - violation raised or exception thrown}

PATTERN TRIGGERS VIOLATION:
- {Example 1}
- {Example 2}

PATTERN ALLOWED (NO VIOLATION):
- {Allowed pattern 1}
- {Allowed pattern 2}

## Context

SCOPE: {Files/directories affected}
EXCLUDE: {Excluded paths}
MANIFEST-TIME: {YES/NO}
SEVERITY: {critical/high/medium/low/convention}

VIOLATION DETAILS:
- Rule ID: {ID}
- Message: "{Violation message}"
- Suggestion: "{How to fix}"

[Additional sections for remediation, context, conventions]

# Added: 2025-12-24

Key Characteristics

Blade Rules

• Enforce proper template syntax
• Prevent inline JavaScript/CSS
• Ensure proper asset loading via bundles
• Validate Blade-specific directives

Common Rules

• File naming conventions
• Route validation
• Project structure
• Prevention of code smells
• Cross-file patterns

Convention Rules

• Bundle organization
• File/directory structure
• Module-level conventions
• Visual grouping principles

Usage

These .expect files serve as:

1. Reference Documentation - Understand what each rule checks
2. Remediation Guides - How to fix violations
3. Behavioral Specification - Test cases for rule validation
4. Developer Training - Learn RSpade conventions

Critical Directives Captured

All documentation reflects the CLAUDE.md directives:

• Fail loud, no silent fallbacks
• One pattern per feature when complete
• No backwards compatibility/dual implementations
• Type-safe URL generation (Rsx::Route)
• Component-first architecture
• Semantic naming conventions
• Framework conventions enforcement

Implementation Status

All 31 rule files have corresponding .expect documentation:

• 6 Blade rules
• 20 Common rules
• 5 Convention rules
• Standard format with detection/context/remediation
• Rule IDs and severity levels documented
• Pattern examples for both violations and allowed code
• Remediation instructions with examples