# 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:
- [x] 6 Blade rules
- [x] 20 Common rules
- [x] 5 Convention rules
- [x] Standard format with detection/context/remediation
- [x] Rule IDs and severity levels documented
- [x] Pattern examples for both violations and allowed code
- [x] Remediation instructions with examples