rails-audit

name	rails-audit
description	Comprehensive Ruby on Rails application audit covering coding standards, testing, security, architecture, and generates results as a PDF deck
user-invocable	true
argument-hint	["output-filename"]
allowed-tools	Bash,Read,Glob,Grep,Write

Rails Application Audit

You are performing a comprehensive audit of a Ruby on Rails application. This audit will cover:

1. Coding Standards & Best Practices
2. Testing & Code Coverage
3. Security Vulnerabilities
4. Code Architecture & Design Patterns
5. Performance Considerations

Audit Process

Phase 1: Project Discovery & Setup

1. Identify Project Structure

   • Read Gemfile and Gemfile.lock to understand dependencies
   • Check Rails version and Ruby version
   • Identify project type (API-only, full-stack, etc.)
   • Read .gitignore to understand which files to exclude from audit

2. Gather Project Metadata

   • Check config/routes.rb for routing structure
   • Review config/database.yml for database configuration
   • Check for presence of config/environments/ files

Phase 2: Coding Standards & Best Practices Audit

Evaluate code against Ruby and Rails community standards:

Ruby Style Guide Checks

• Indentation: 2 spaces (not tabs)
• Line length: Max 120 characters (some teams use 80)
• Method length: Methods should be < 10 lines ideally
• Class length: Classes should be < 100 lines
• Naming conventions:
  • snake_case for methods, variables, files
  • CamelCase for classes and modules
  • SCREAMING_SNAKE_CASE for constants
• String literals: Prefer single quotes unless interpolation needed
• Hash syntax: Use modern syntax key: value for symbol keys
• Blocks: Use {} for single-line, do...end for multi-line

Rails Best Practices

• Fat models, skinny controllers: Business logic in models, not controllers
• RESTful design: Controllers follow REST conventions
• DRY principle: No code duplication
• Service objects: Complex business logic extracted to service objects
• Query optimization: N+1 query prevention, proper eager loading
• Concerns usage: Proper use of ActiveSupport::Concern
• Strong parameters: All controller actions use strong parameters
• Callbacks: Minimal and appropriate use of before/after callbacks
• Database migrations: Reversible, properly indexed
• Background jobs: Long-running tasks in background jobs

Search for common anti-patterns:

• Controllers with too many actions
• Models with too many responsibilities
• Direct database queries in views
• Missing validations on models
• Callbacks doing too much work
• Missing database indexes on foreign keys

Phase 3: Testing & Coverage Audit

1. Test Framework Detection

   • Check if using RSpec, Minitest, or other
   • Identify test directory structure (spec/ or test/)

2. Test Coverage Analysis

   • Look for SimpleCov or similar coverage tool configuration
   • Check for .simplecov file
   • If coverage reports exist, analyze them
   • Identify untested or under-tested areas

3. Test Quality Assessment

   • Model tests: Validations, associations, scopes, methods
   • Controller tests: All actions, edge cases, authentication
   • Integration/request tests: Full user flows
   • System/feature tests: End-to-end scenarios
   • Check for test factories (FactoryBot) or fixtures
   • Evaluate test naming and organization
   • Check for proper use of test helpers and shared examples

4. Test Anti-patterns

   • Tests that are too slow
   • Tests with database dependencies that could be unit tests
   • Brittle tests (too dependent on implementation)
   • Missing edge case tests
   • No negative test cases

Phase 4: Security Vulnerability Audit

Scan for common security issues:

Authentication & Authorization

• Authentication mechanism (Devise, custom, etc.)
• Authorization implementation (Pundit, CanCanCan, custom)
• Password requirements and hashing
• Session management
• CSRF protection enabled
• Secure cookie settings

Common Vulnerabilities (OWASP Top 10)

• SQL Injection: Raw SQL usage without sanitization
• XSS (Cross-Site Scripting): Unsafe rendering of user input
• Mass Assignment: Missing strong parameters
• Insecure Direct Object References: Missing authorization checks
• CSRF: Disabled CSRF protection
• Security Misconfiguration:
  • Debug mode in production
  • Exposed secrets
  • Missing security headers
• Sensitive Data Exposure:
  • Secrets in version control
  • API keys in code
  • Database credentials hardcoded
• Missing authentication: Unprotected endpoints
• Insecure dependencies: Outdated gems with known vulnerabilities

Files to Check

• config/initializers/ for security settings
• Gemfile.lock for vulnerable gem versions
• .env files (should be in .gitignore)
• config/secrets.yml or credentials.yml.enc
• Controller actions for authentication/authorization

Tools Integration

• Check for Brakeman configuration
• Check for bundler-audit usage
• Look for security-related gems

Phase 5: Code Architecture & Design Audit

Evaluate the overall architecture:

Directory Structure

• Proper organization of app/ directory
• Use of app/services/, app/queries/, app/forms/ etc.
• Appropriate use of lib/ directory
• app/concerns/ usage

Design Patterns

• Service objects for complex operations
• Query objects for complex queries
• Form objects for complex forms
• Presenters/Decorators for view logic
• Interactors for multi-step operations
• Repository pattern where appropriate

Dependencies & Coupling

• Tight coupling between components
• Circular dependencies
• God objects (classes doing too much)
• Inappropriate dependencies

Database Design

• Proper normalization
• Missing indexes
• Missing foreign key constraints
• N+1 query problems
• Inefficient queries

API Design (if applicable)

• RESTful endpoint design
• Proper HTTP status codes
• API versioning strategy
• Serialization approach
• Rate limiting
• Authentication mechanism

Phase 6: Performance Considerations

Review for performance issues:

• Database queries: N+1 queries, missing indexes
• Caching: Use of fragment caching, Russian doll caching
• Background jobs: Proper use of Sidekiq/Resque/DelayedJob
• Asset pipeline: Proper minification and compression
• Memory usage: Large object instantiation, memory leaks
• Code complexity: Cyclomatic complexity issues

Phase 7: Generate Audit Report

After completing the audit, generate a comprehensive report with:

1. Executive Summary

   • Overall health score
   • Critical issues count
   • Major findings

2. Detailed Findings by Category

   • Coding Standards (issues, recommendations)
   • Testing Coverage (coverage %, gaps)
   • Security Issues (critical, high, medium, low)
   • Architecture Assessment (strengths, weaknesses)
   • Performance Issues (bottlenecks identified)

3. Prioritized Recommendations

   • Critical (fix immediately)
   • High (fix soon)
   • Medium (fix in next sprint)
   • Low (nice to have)

4. Metrics Dashboard

   • Code quality metrics
   • Test coverage percentage
   • Security score
   • Technical debt estimation

Output Format

Generate the audit report as a presentation deck with the following structure:

Slide Structure

# Slide 1: Title
- Project Name: [Name]
- Audit Date: [Date]
- Ruby Version: [Version]
- Rails Version: [Version]

---

# Slide 2: Executive Summary
- Overall Score: [X/100]
- Critical Issues: [N]
- High Priority: [N]
- Medium Priority: [N]
- Low Priority: [N]

---

# Slide 3: Audit Scope
- Total Files Analyzed: [N]
- Lines of Code: [N]
- Models: [N]
- Controllers: [N]
- Services: [N]
- Tests: [N]

---

# Slide 4: Coding Standards
## Issues Found
- [Category]: [Count]
- [Category]: [Count]

## Top Issues
1. [Issue with file reference]
2. [Issue with file reference]
3. [Issue with file reference]

---

# Slide 5: Testing & Coverage
- Overall Coverage: [X%]
- Model Coverage: [X%]
- Controller Coverage: [X%]
- Integration Tests: [Pass/Fail]

## Coverage Gaps
- [Area with low coverage]
- [Area with no tests]

---

# Slide 6: Security Assessment
## Vulnerabilities Found
- Critical: [N]
- High: [N]
- Medium: [N]
- Low: [N]

## Top Security Issues
1. [Issue description]
2. [Issue description]
3. [Issue description]

---

# Slide 7: Architecture Review
## Strengths
- [Positive finding]
- [Positive finding]

## Areas for Improvement
- [Issue]
- [Issue]

---

# Slide 8: Performance Analysis
## Identified Bottlenecks
- [Performance issue]
- [Performance issue]

## Optimization Opportunities
- [Recommendation]
- [Recommendation]

---

# Slide 9: Critical Issues (Details)
[Detailed breakdown of critical issues]

---

# Slide 10: Recommendations
## Immediate Actions
1. [Action]
2. [Action]

## Short-term (Next Sprint)
1. [Action]
2. [Action]

## Long-term (Next Quarter)
1. [Action]
2. [Action]

---

# Slide 11: Conclusion
- Overall assessment
- Next steps
- Timeline recommendations

Execution Steps

1. Create Markdown Deck: Write audit findings to a markdown file named rails-audit-report-[date].md

2. Convert to PDF: Use one of these approaches:

   • Marp: If available, use Marp for markdown to PDF
   • Pandoc: Convert markdown to PDF with beamer
   • Reveal.js + Decktape: For web-based presentations
   • mdpdf: Simple markdown to PDF converter

3. Output Location: Save both markdown and PDF in project root or docs/ directory

Tool Usage Guidelines

1. Respect .gitignore: Before scanning, read .gitignore and exclude listed files/directories
2. Use Glob for file discovery: Find Ruby files (*.rb), Rails files
3. Use Grep for pattern matching: Search for anti-patterns, vulnerabilities
4. Use Read for detailed analysis: Read configuration files, critical code files
5. Generate statistics: Count files, lines, calculate metrics
6. Create visualizations: Use ASCII charts where appropriate in the report

Command Usage

When invoked via /rails-audit [filename]:

• If filename provided: Use as output filename (default: markdown, also generate PDF)
• If no filename: Use default rails-audit-report-YYYY-MM-DD.md

Execution Workflow

1. Announce audit start and estimated scope
2. Read .gitignore to build exclusion list
3. Discover project structure (files, directories)
4. Run each audit phase sequentially
5. Collect findings and metrics
6. Generate markdown deck with findings
7. Convert markdown to PDF
8. Present summary and provide file locations
9. Offer to open or display the results

Important Notes

• Be thorough but respect the .gitignore file
• Provide specific file and line references for issues
• Give constructive recommendations, not just criticism
• Prioritize findings by severity
• Include both positive findings and issues
• Make the report actionable with clear next steps
• Ensure PDF is professionally formatted and readable
• Include code snippets in findings where relevant (but keep slides readable)

---

Begin the comprehensive Rails application audit now. Work through each phase systematically and generate a professional audit report deck.